openapi: 3.0.1 info: title: VILLASweb Backend API Documentation description: API for VILLASweb Backend implementation in Go. Documentation in progress... please be patient. Removed endpoints are marked with "REMOVED". New endpoints are marked with "NEW". version: 1.0.0 servers: - url: http://111.222.333.444:5555/api/v1 tags: - name: authentication description: Manage user authentication - name: counts description: Get counters for database elements - name: users description: Manage Users - name: files description: Manage Files - name: simulators description: Manage Simulators - name: projects description: (REMOVED) Manage Projects - name: simulations description: Manage Simulations - name: models description: Manage Models - name: visualizations description: Manage Visualizations - name: uploads description: Manage Uploads (REMOVED, now in files) paths: /authenticate: post: tags: - authentication summary: Authenticate a user operationId: authenticateUser requestBody: description: "User object to authenticate" required: true content: application/json: schema: $ref: '#/components/schemas/User' responses: 200: description: OK. content: application/json: schema: type: object properties: success: type: boolean message: type: string token: type: object properties: {} 400: description: Bad request. Unable to create user with existing username, username is already taken 401: description: Unauthorized access. Invalid or missing credentials. 403: description: Access forbidden. 404: description: Not found. content: application/json: schema: type: object properties: success: type: boolean example: false message: type: string example: error message 500: description: Internal server error. Unable to compare passwords. /counts: get: tags: - counts summary: Get counters for all elements in the database operationId: getCounts responses: 200: description: OK. content: application/json: schema: type: object properties: simulations: type: integer description: number of simulations users: type: integer description: number of users simulators: type: integer description: number of simulators projects: type: integer description: number of projects visualizations: type: integer description: number of visualizations 401: description: Unauthorized access. 403: description: Access forbidden. 404: description: Not found. Unable to find at least one of the count targets. 500: description: Internal server error. /simulations: get: tags: - simulations summary: Get all available simulations description: Return a JSON representation of all simulations operationId: getSimulations responses: 200: description: OK. content: application/json: schema: type: array items: $ref: '#/components/schemas/Simulation' 401: description: Unauthorized access. 403: description: Access forbidden. 404: description: Not found. No simulations found. 500: description: Internal server error. post: tags: - simulations summary: Add a new simulation to the database operationId: addSimulation requestBody: description: "Simulation object to add to DB" required: true content: application/json: schema: $ref: '#/components/schemas/Simulation' responses: 200: description: OK. 401: description: Unauthorized access. 403: description: Access forbidden. 500: description: Internal server error. /simulations/{SimulationID}: put: tags: - simulations summary: Update properties of simulation with ID SimulationID operationId: updateSimulationProperties parameters: - in: path name: SimulationID description: ID of a simulation required: true schema: type: integer requestBody: description: "Simulation object with new properties" required: true content: application/json: schema: $ref: '#/components/schemas/Simulation' responses: 200: description: OK. 401: description: Unauthorized access. 403: description: Access forbidden. 404: description: Not found. Unable to find simulation or user. 500: description: Internal server error. Unable to save user. get: tags: - simulations summary: Get properties of simulation with ID SimulationID operationId: getSimulationProperties parameters: - in: path name: SimulationID description: ID of a simulation required: true schema: type: integer responses: 200: description: OK. content: application/json: schema: $ref: '#/components/schemas/Simulation' 401: description: Unauthorized access. 403: description: Access forbidden. 404: description: Not found. Unable to find simulation. 500: description: Internal server error. delete: tags: - simulations summary: Delete simulation with ID SimulationID operationId: deleteSimulation parameters: - in: path name: SimulationID description: ID of a simulation required: true schema: type: integer responses: 200: description: OK. 401: description: Unauthorized access. 403: description: Access forbidden. 404: description: Not found. Unable to find simulation. 500: description: Internal server error. /files: get: tags: - files summary: (REMOVED) Get files of user operationId: (REMOVED) getFilesOfUser responses: 200: description: OK. content: application/json: schema: type: array items: $ref: '#/components/schemas/File' 401: description: Unauthorized access. 403: description: Access forbidden. 404: description: Not found. No files found. 500: description: Internal server error. Could not retrieve user's files. post: tags: - files summary: (REMOVED) Add a new file to the database operationId: (REMOVED) addFile requestBody: description: "File object to be added" required: true content: application/json: schema: $ref: '#/components/schemas/File' responses: 200: description: OK. 400: description: Bad request. File could not be uploaded because unable to process incoming form. 401: description: Unauthorized access. 403: description: Access forbidden. 404: description: Not found. User not found. 500: description: Internal server error. Unable to save reference file or user OR unable to create directory. /files/{FileID}: get: tags: - files summary: (REMOVED) Get properties of file with ID FileID operationId: (REMOVED) getFileProperties parameters: - in: path name: FileID description: ID of a file required: true schema: type: integer - in: header name: X-Request-FileDesc description: Set false if file itself, true if file description shall be returned required: true schema: type: boolean responses: 200: description: OK. content: application/json: schema: $ref: '#/components/schemas/File' model/x-cim.zip: schema: type: string format: byte 401: description: Unauthorized access. 403: description: Access forbidden. 404: description: Not found. File not found. 500: description: Internal server error. put: tags: - files summary: (REMOVED) Update properties of file with ID FileID operationId: (REMOVED) updateFileProperties requestBody: description: "File object to be updated" required: true content: application/json: schema: $ref: '#/components/schemas/File' parameters: - in: path name: FileID description: ID of a file required: true schema: type: integer responses: 200: description: OK. 400: description: Bad request. File could not be uploaded because unable to process incoming form. 401: description: Unauthorized access. 403: description: Access forbidden. 404: description: Not found. File not found. 500: description: Internal server error. Unable to save reference file or user OR unable to create directory. delete: tags: - files summary: (REMOVED) Delete file with ID FileID operationId: (REMOVED) deleteFile parameters: - in: path name: FileID description: ID of a file required: true schema: type: integer responses: 200: description: OK. 401: description: Unauthorized access. 403: description: Access forbidden. 404: description: Not found. File not found. 500: description: Internal server error. Unable to remove file. /projects: get: tags: - projects summary: (REMOVED) Get projects of user operationId: (REMOVED) getProjects responses: 200: description: OK. content: application/json: schema: type: array items: $ref: '#/components/schemas/Project' 401: description: Unauthorized access. 403: description: Access forbidden. 404: description: Not found. No projects found. 500: description: Internal server error. post: tags: - projects summary: (REMOVED) Add a new project to the database operationId: (REMOVED) addProject requestBody: description: "Project object to add to DB" required: true content: application/json: schema: $ref: '#/components/schemas/Project' responses: 200: description: OK. 401: description: Unauthorized access. 403: description: Access forbidden. 404: description: Not found. Unknown user. 500: description: Internal server error. Unable to save user or project. /projects/{ProjectID}: put: tags: - projects summary: (REMOVED) Update properties of project with ID ProjectID operationId: (REMOVED) updateProjectProperties parameters: - in: path name: ProjectID description: ID of a project required: true schema: type: integer requestBody: description: "Project object with new properties" required: true content: application/json: schema: $ref: '#/components/schemas/Project' responses: 200: description: OK. 400: description: Bad request. Unable to process incoming form. 401: description: Unauthorized access. 403: description: Access forbidden. 404: description: Not found. Project not found. 500: description: Internal server error. Unable to save project or user. get: tags: - projects summary: (REMOVED) Get properties of project with ID ProjectID operationId: (REMOVED) getProjectProperties parameters: - in: path name: ProjectID description: ID of a project required: true schema: type: integer responses: 200: description: OK. content: application/json: schema: $ref: '#/components/schemas/Project' 401: description: Unauthorized access. 403: description: Access forbidden. 404: description: Not found. Project not found. 500: description: Internal server error. delete: tags: - projects summary: (REMOVED) Delete project with ID ProjectID operationId: (REMOVED) deleteProject parameters: - in: path name: ProjectID description: ID of a project required: true schema: type: integer responses: 200: description: OK. 401: description: Unauthorized access. 403: description: Access forbidden. 404: description: Not found. Project not found. 500: description: Internal server error. Unable to remove project. /models: get: tags: - models summary: (REMOVED) Get simulation models of user operationId: (REMOVED) getModels responses: 200: description: OK. content: application/json: schema: type: array items: $ref: '#/components/schemas/Model' 401: description: Unauthorized access. 403: description: Access forbidden. 404: description: Not found. No simulation models found. 500: description: Internal server error. post: tags: - models summary: (REMOVED) Add a new Model to the database operationId: (REMOVED) addModel requestBody: description: "Model object to add to DB" required: true content: application/json: schema: $ref: '#/components/schemas/Model' responses: 200: description: OK. 400: description: Bad request. Unable to process incoming form. 401: description: Unauthorized access. 403: description: Access forbidden. 500: description: Internal server error. Unable to save simulation or simulation model. /models/{ModelID}: put: tags: - models summary: (REMOVED) Update properties of Model with ID ModelID operationId: (REMOVED) updateModelProperties parameters: - in: path name: ModelID description: ID of a Model required: true schema: type: integer requestBody: description: "Model object with new properties" required: true content: application/json: schema: $ref: '#/components/schemas/Model' responses: 200: description: OK. 400: description: Bad request. Unable to process incoming form. 401: description: Unauthorized access. 403: description: Access forbidden. 404: description: Not found. Simulation model not found. 500: description: Internal server error. Unable to save simulation model. get: tags: - models summary: (REMOVED) Get properties of Model with ID ModelID operationId: (REMOVED) getModelProperties parameters: - in: path name: ModelID description: ID of a Model required: true schema: type: integer responses: 200: description: OK. content: application/json: schema: $ref: '#/components/schemas/Model' 401: description: Unauthorized access. 403: description: Access forbidden. 404: description: Not found. Simulation model not found. 500: description: Internal server error. delete: tags: - models summary: (REMOVED) Delete Model with ID ModelID operationId: (REMOVED) deleteModel parameters: - in: path name: ModelID description: ID of a Model required: true schema: type: integer responses: 200: description: OK. 401: description: Unauthorized access. 403: description: Access forbidden. 404: description: Not found. Simulation or simulation model not found. 500: description: Internal server error. Unable to save changed simulation or to remove simulation model. simulations/{SimulationID}/models/{ModelID}/file: get: tags: - simulations summary: (NEW) Get file from Model with ID ModelID operationId: getFileFromModel parameters: - in: path name: ModelID description: ID of a Model required: true schema: type: integer requestBody: description: "Info about file to download" required: true content: application/json: schema: required: - NumberOfFiles - MIMEType type: object properties: NumberOfFiles: type: integer MIMEType: type: string examples: cim: summary: "An example for CIM file" value: NumberOfFiles: 1 MIMEType: "model/x-cim.zip" responses: 200: description: OK. content: model/x-cim.zip: schema: type: string format: byte 401: description: Unauthorized access. 403: description: Access forbidden. 404: description: Not found. Simulation model not found. 500: description: Internal server error. put: tags: - simulations summary: (NEW) Update (Overwrite) file of Model with ID ModelID, File object has to be in database operationId: updateFileForModel parameters: - in: path name: ModelID description: ID of a Model required: true schema: type: integer requestBody: description: "File to be updated for simulation model" required: true content: model/x-cim.zip: schema: type: string format: byte responses: 200: description: OK. 401: description: Unauthorized access. 403: description: Access forbidden. 404: description: Not found. Simulation model not found. 500: description: Internal server error. Unable to save simulation model. /simulators: get: tags: - simulators summary: Get simulators operationId: getSimulators responses: 200: description: OK. content: application/json: schema: type: array items: $ref: '#/components/schemas/Simulator' 401: description: Unauthorized access. 403: description: Access forbidden. 404: description: Not found. No simulators found. 500: description: Internal server error. post: tags: - simulators summary: Add a new Simulator to the database operationId: addSimulator requestBody: description: "Simulator object to add to DB" required: true content: application/json: schema: $ref: '#/components/schemas/Simulator' responses: 200: description: OK. 400: description: Bad request. Unable to process incoming form. 401: description: Unauthorized access. 403: description: Access forbidden. 500: description: Internal server error. Unable to save simulator. /simulators/{SimulatorID}: put: tags: - simulators summary: Update properties of Simulator with ID SimulatorID operationId: updateSimulatorProperties parameters: - in: path name: SimulatorID description: ID of a Simulator required: true schema: type: integer requestBody: description: "Simulator object with new properties" required: true content: application/json: schema: $ref: '#/components/schemas/Simulator' responses: 200: description: OK. 401: description: Unauthorized access. 403: description: Access forbidden. 404: description: Not found. Simulator not found. 500: description: Internal server error. Unable to save simulator. get: tags: - simulators summary: Get properties of Simulator with ID SimulatorID operationId: getSimulatorProperties parameters: - in: path name: SimulatorID description: ID of a Simulator required: true schema: type: integer responses: 200: description: OK. content: application/json: schema: $ref: '#/components/schemas/Simulator' 401: description: Unauthorized access. 403: description: Access forbidden. 404: description: Not found. Simulator not found. 500: description: Internal server error. delete: tags: - simulators summary: Delete Simulator with ID SimulatorID operationId: deleteSimulator parameters: - in: path name: SimulatorID description: ID of a Simulator required: true schema: type: integer responses: 200: description: OK. 401: description: Unauthorized access. 403: description: Access forbidden. 404: description: Not found. Simulator not found. 500: description: Internal server error. Unable to remove simulator. post: tags: - simulators summary: Send actions to Simulator with ID SimulatorID operationId: sendActionsToSimulator parameters: - in: path name: SimulatorID description: ID of a Simulator required: true schema: type: integer requestBody: description: "Array containing simulator actions" required: true content: application/json: schema: type: array items: type: string responses: 200: description: OK. 400: description: Bad request. Unable to process incoming form. 401: description: Unauthorized access. 403: description: Access forbidden. 404: description: Not found. Simulator not found. 500: description: Internal server error. Unable to send actions to simulator. /users: get: tags: - users summary: Get users operationId: getUsers responses: 200: description: OK. content: application/json: schema: type: array items: $ref: '#/components/schemas/User' 401: description: Unauthorized access. 403: description: Access forbidden. 404: description: Not found. No users found. 500: description: Internal server error. post: tags: - users summary: Add a new User to the database operationId: addUser requestBody: description: "User object to add to DB" required: true content: application/json: schema: $ref: '#/components/schemas/User' responses: 200: description: OK. 400: description: Bad request. Unable to process incoming form. Username is already taken 401: description: Unauthorized access. 403: description: Access forbidden. 500: description: Internal server error. Unable to save user. /users/{UserID}: put: tags: - users summary: Update properties of User with ID UserID operationId: updateUserProperties parameters: - in: path name: UserID description: ID of a User required: true schema: type: integer requestBody: description: "User object with new properties" required: true content: application/json: schema: $ref: '#/components/schemas/User' responses: 200: description: OK. 400: description: Bad request. Username is already taken. 401: description: Unauthorized access. 403: description: Access forbidden. 404: description: Not found. User not found. 500: description: Internal server error. get: tags: - users summary: Get properties of User with ID UserID operationId: getUserProperties parameters: - in: path name: UserID description: ID of a User required: true schema: type: integer responses: 200: description: OK. content: application/json: schema: $ref: '#/components/schemas/User' 401: description: Unauthorized access. 403: description: Access forbidden. 404: description: Not found. User not found. 500: description: Internal server error. delete: tags: - users summary: Delete User with ID UserID operationId: deleteUser parameters: - in: path name: UserID description: ID of a User required: true schema: type: integer responses: 200: description: OK. 401: description: Unauthorized access. 403: description: Access forbidden. 404: description: Not found. User not found. 500: description: Internal server error. Unable to remove user. /users/me: get: tags: - users summary: Get properties of user that issues the request (REMOVED) operationId: getUserPropertiesCurrent responses: 200: description: OK. content: application/json: schema: $ref: '#/components/schemas/User' 401: description: Unauthorized access. 403: description: Access forbidden. 404: description: Not found. User not found. 500: description: Internal server error. /visualizations: get: tags: - visualizations summary: (REMOVED) Get all available visualizations description: (REMOVED) Return a JSON representation of all visualizations operationId: (REMOVED) getVisualizations responses: 200: description: OK. content: application/json: schema: type: array items: $ref: '#/components/schemas/Visualization' 401: description: Unauthorized access. 403: description: Access forbidden. 404: description: Not found. No visualizations found. 500: description: Internal server error. post: tags: - visualizations summary: (REMOVED) Add a new visualization to the database operationId: (REMOVED) addVisualization requestBody: description: "Visualization object to add to DB" required: true content: application/json: schema: $ref: '#/components/schemas/Visualization' responses: 200: description: OK. 400: description: Bad request. Unable to process incoming form. 401: description: Unauthorized access. 403: description: Access forbidden. 404: description: Not found. Project of visualization not found. 500: description: Internal server error. Unable to save project or visualization. /visualization/{VisualizationID}: put: tags: - visualizations summary: (REMOVED) Update properties of Visualization with ID VisualizationID operationId: (REMOVED) updateVisualizationrProperties parameters: - in: path name: VisualizationID description: ID of a Visualization required: true schema: type: integer requestBody: description: "Visualization object with new properties" required: true content: application/json: schema: $ref: '#/components/schemas/Visualization' responses: 200: description: OK. 400: description: Bad request. Unable to process incoming form. 401: description: Unauthorized access. 403: description: Access forbidden. 404: description: Not found. Visualization not found. 500: description: Internal server error. Unable to save Visualization. get: tags: - visualizations summary: (REMOVED) Get properties of Visualization with ID VisualizationID operationId: (REMOVED) getVisualizationProperties parameters: - in: path name: VisualizationID description: ID of a Visualization required: true schema: type: integer responses: 200: description: OK. content: application/json: schema: $ref: '#/components/schemas/Visualization' 401: description: Unauthorized access. 403: description: Access forbidden. 404: description: Not found. Visualization not found. 500: description: Internal server error. delete: tags: - visualizations summary: (REMOVED) Delete Visualization with ID VisualizationID operationId: (REMOVED) deleteVisualization parameters: - in: path name: VisualizationID description: ID of a Visualization required: true schema: type: integer responses: 200: description: OK. 401: description: Unauthorized access. 403: description: Access forbidden. 404: description: Not found. Visualization or project of visualization not found. 500: description: Internal server error. Unable to remove visualization or to save changed project. /uploads: post: tags: - uploads summary: (REMOVED) Upload a new file to the database operationId: (REMOVED) uploadFile requestBody: description: "File object to upload TODO CHANGE TO FORM" required: true content: application/json: schema: $ref: '#/components/schemas/File' responses: 200: description: OK. 400: description: Bad request. Unable to process incoming form. 401: description: Unauthorized access. 403: description: Access forbidden. 404: description: Not found. User or reference file not found. 500: description: Internal server error. Unable to save user or reference file OR unable to create directory. components: schemas: Project: required: - Name - SimulationID - UserID type: object properties: Name: type: string UserID: type: integer SimulationID: type: integer Visualization: required: - Name - Grid - ProjectID - UserID type: object properties: Name: type: string Grid: type: integer UserID: type: integer ProjectID: type: integer User: required: - Username - Password - Role - Mail type: object properties: Username: type: string Password: type: string Role: type: string Mail: type: string Simulation: required: - ID - Name - UserID type: object properties: ID: type: integer Name: type: string Running: type: boolean UserID: type: integer StartParameters: type: object properties: {} File: required: - Name - Path - Type - Size - Date - UserID type: object properties: Name: type: string Path: type: string Type: type: string Size: type: integer ImageHeight: type: integer ImageWidth: type: integer UserID: type: integer ModelID: type: integer Date: type: string Simulator: required: - UUID - Host - ModelType type: object properties: UUID: type: string Host: type: string ModelType: type: string UpTime: type: integer State: type: string StateUpdateAt: type: string Properties: type: object properties: {} RawProperties: type: object properties: {} Model: required: - Name - OutputLength - InputLength - BelongsToSimulationID - BelongsToSimulatorID type: object properties: Name: type: string OutputLength: type: integer InputLength: type: integer SimulationID: type: integer SimulatorID: type: integer StartParameters: type: object properties: {} OutputMapping: type: array items: $ref: '#/components/schemas/Signal' InputMapping: type: array items: $ref: '#/components/schemas/Signal' Signal: required: - Name - Unit - ModelID type: object properties: Name: type: string Unit: type: string ModelID: type: integer Widget: required: - Name - Type - Width - Height - MinWidth - MinHeight - X - Y - Z - IsLocked - VisualizationID type: object properties: Name: type: string Type: type: string Width: type: integer Height: type: integer MinWidth: type: integer MinHeight: type: integer X: type: integer Y: type: integer Z: type: integer IsLocked: type: boolean VisualizationID: type: integer CustomProperties: type: object properties: {}