VILLASweb-backend-go/doc/api/api.yaml
2019-04-15 17:05:36 +02:00

1100 lines
29 KiB
YAML

openapi: 3.0.1
info:
title: VILLASweb API
description: API for VILLASweb. Documentation in progress... please be patient
version: 1.0.0
servers:
- url: http://111.222.333.444:5555/api/v1
tags:
- name: simulations
description: Manage Simulations
- name: counts
description: Get counters for database elements
- name: files
description: Manage Files
- name: projects
description: Manage Projects
- name: simulationmodels
description: Manage SimulationModels
- name: simulators
description: Manage Simulators
- name: uploads
description: Manage Uploads
- name: users
description: Manage Users
- name: visualizations
description: Manage Visualizations
paths:
/simulations:
get:
tags:
- simulations
summary: Get all available simulations
description: Return a JSON representation of all simulations
operationId: getSimulations
responses:
400:
description: Unable to receive simulations
content: {}
200:
description: Simulations received successfully TODO CHECK CODE!
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Simulation'
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:
400:
description: Unable to find user or unable to create simulation
content: {}
500:
description: Unable to save user
content: {}
/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:
500:
description: Unable to find user or unable to save user or
content: {}
400:
description: PUT Simulation Unknown for ID or unable to save simulation
content: {}
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: Simulation received successfully (TODO CHECK CODE)
content:
application/json:
schema:
$ref: '#/components/schemas/Simulation'
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: TODO RESPONSES!
content: {}
/counts:
get:
tags:
- counts
summary: Get counters for all elements in the database
operationId: getCounts
responses:
200:
description: Counts successful (TODO CHECK IF CODE CORRECT!)
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
/files:
get:
tags:
- files
summary: Get files of user
operationId: getFilesOfUser
responses:
200:
description: Files obtained successfully (TODO CHECK CODE!)
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/File'
500:
description: Could not retrieve user's files
content: {}
/files/{FileID}:
get:
tags:
- files
summary: Get properties of file with ID FileID
operationId: getFileProperties
parameters:
- in: path
name: FileID
description: ID of a file
required: true
schema:
type: integer
responses:
200:
description: File received successfully (TODO CHECK CODE)
content:
application/json:
schema:
$ref: '#/components/schemas/File'
400:
description: GET Unknown file for ID
content: {}
delete:
tags:
- files
summary: Delete file with ID FileID
operationId: deleteFile
parameters:
- in: path
name: FileID
description: ID of a file
required: true
schema:
type: integer
responses:
200:
description: TODO RESPONSES!
content: {}
400:
description: DELETE unknown file for id
content: {}
500:
description: Unable to remove file
content: {}
/projects:
get:
tags:
- projects
summary: Get projects of user
operationId: getProjects
responses:
200:
description: Projects received successfully TODO CHECK CODE!
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Project'
400:
description: Unable to receive projects
content: {}
post:
tags:
- projects
summary: Add a new project to the database
operationId: addProject
requestBody:
description: "Project object to add to DB"
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Project'
responses:
400:
description: Unable to find user or unable to save user or unknown project for id
content: {}
500:
description: Unable to create project or unable to save project
content: {}
/projects/{ProjectID}:
put:
tags:
- projects
summary: Update properties of project with ID ProjectID
operationId: 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:
500:
description: Unable to find user or unable to save user or unable to find simulation of project or unable to save simulation of project or unable to save project
content: {}
400:
description: PUT Simulation Unknown for ID
content: {}
get:
tags:
- projects
summary: Get properties of project with ID ProjectID
operationId: getProjectProperties
parameters:
- in: path
name: ProjectID
description: ID of a project
required: true
schema:
type: integer
responses:
200:
description: Project received successfully (TODO CHECK CODE)
content:
application/json:
schema:
$ref: '#/components/schemas/Project'
400:
description: GET Unknown project for ID
content: {}
delete:
tags:
- projects
summary: Delete project with ID ProjectID
operationId: deleteProject
parameters:
- in: path
name: ProjectID
description: ID of a project
required: true
schema:
type: integer
responses:
400:
description: DELETE Unknown project
content: {}
500:
description: Unable to find user or unable to save user or unable to remove project
content: {}
/models:
get:
tags:
- simulationmodels
summary: Get simulation models of user
operationId: getSimulationModels
responses:
200:
description: SimulationModel received successfully TODO CHECK CODE!
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/SimulationModel'
400:
description: Unable to find SimulationModel
content: {}
post:
tags:
- simulationmodels
summary: Add a new SimulationModel to the database
operationId: addSimulationModel
requestBody:
description: "SimulationModel object to add to DB"
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SimulationModel'
responses:
400:
description: Unable to find Simulation
content: {}
500:
description: Unable to save simulation or unable to create simulation model
content: {}
/models/{SimulationModelID}:
put:
tags:
- simulationmodels
summary: Update properties of SimulationModel with ID SimulationModelID
operationId: updateSimulationModelProperties
parameters:
- in: path
name: SimulationModelID
description: ID of a SimulationModel
required: true
schema:
type: integer
requestBody:
description: "SimulationModel object with new properties"
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SimulationModel'
responses:
500:
description: Unable to save SimulationModel
content: {}
400:
description: Unable to find SimulationModel
content: {}
get:
tags:
- simulationmodels
summary: Get properties of SimulationModel with ID SimulationModelID
operationId: getSimulationModelProperties
parameters:
- in: path
name: SimulationModelID
description: ID of a SimulationModel
required: true
schema:
type: integer
responses:
200:
description: SimulationModel received successfully (TODO CHECK CODE)
content:
application/json:
schema:
$ref: '#/components/schemas/SimulationModel'
400:
description: GET Unknown SimulationModel for ID
content: {}
delete:
tags:
- simulationmodels
summary: Delete SimulationModel with ID SimulationModelID
operationId: deleteSimulationModel
parameters:
- in: path
name: SimulationModelID
description: ID of a SimulationModel
required: true
schema:
type: integer
responses:
400:
description: DELETE Unknown SimulationModel
content: {}
500:
description: Unable to find Simulation or unable to save changed simulation or unable to remove SimulationModel
content: {}
/simulators:
get:
tags:
- simulators
summary: Get simulators
operationId: getSimulators
responses:
200:
description: Simulators received successfully TODO CHECK CODE!
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Simulator'
400:
description: Unable to find Simulators
content: {}
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:
500:
description: Unable to create simulator
content: {}
/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:
500:
description: PUT ERROR finding simulator or Unable to save Simulator
content: {}
400:
description: PUT Unknown simulator
content: {}
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: Simulator received successfully (TODO CHECK CODE)
content:
application/json:
schema:
$ref: '#/components/schemas/Simulator'
400:
description: GET Unknown Simulator for ID
content: {}
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:
400:
description: DELETE Unknown Simulator
content: {}
500:
description: Unable to remove Simulator
content: {}
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:
500:
description: Unable to send actions to simulator
content: {}
400:
description: POST unknown simulator
content: {}
/uploads:
post:
tags:
- uploads
summary: Upload a new file to the database
operationId: uploadFile
requestBody:
description: "File object to upload TODO CHANGE TO FORM"
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/File'
responses:
500:
description: File could not be uploaded and GET unable to find user or unable to save reference file or unable to save user or unable to create directory
content: {}
400:
description: File could not be uploaded because unable to process incoming form
content: {}
/users:
get:
tags:
- users
summary: Get users
operationId: getUsers
responses:
200:
description: Users received successfully TODO CHECK CODE!
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
400:
description: Unable to receive Users
content: {}
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:
500:
description: Unable to create user
content: {}
400:
description: Unable to create user with existing username, username is already taken
content: {}
/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:
500:
description: PUT Unknown user
content: {}
404:
description: Unable to find user
content: {}
403:
description: Invalid authorization
content: {}
400:
description: Username is already taken
content: {}
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: User received successfully (TODO CHECK CODE)
content:
application/json:
schema:
$ref: '#/components/schemas/User'
400:
description: GET Unknown User for ID
content: {}
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:
400:
description: DELETE Unknown User
content: {}
500:
description: Unable to remove User
content: {}
/users/me:
get:
tags:
- users
summary: Get properties of user that issues the request
operationId: getUserPropertiesCurrent
responses:
200:
description: User received successfully (TODO CHECK CODE)
content:
application/json:
schema:
$ref: '#/components/schemas/User'
400:
description: GET Unknown User for ID (TODO CHECK CODE)
content: {}
/authenticate:
post:
tags:
- users
summary: Authenticate a user
operationId: authenticateUser
requestBody:
description: "User object to authenticate"
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/User'
responses:
500:
description: Unable to compare passwords, internal server error
content: {}
400:
description: Unable to create user with existing username, username is already taken
content: {}
401:
description: Invalid or missing credentials, unkown username or wrong password
content: {}
200:
description: Authentication successful (TODO CHECK CODE and TOKEN)
content:
application/json:
schema:
type: object
properties:
Success:
type: boolean
message:
type: string
token:
type: object
properties: {}
/visualizations:
get:
tags:
- visualizations
summary: Get all available visualizations
description: Return a JSON representation of all visualizations
operationId: getVisualizations
responses:
400:
description: Unable to receive visualizations
content: {}
200:
description: Visualizations received successfully TODO CHECK CODE!
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Visualization'
post:
tags:
- visualizations
summary: Add a new visualization to the database
operationId: addVisualization
requestBody:
description: "Visualization object to add to DB"
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Visualization'
responses:
400:
description: Unable to find project
content: {}
500:
description: Unable to save project or unable to create visualization
content: {}
/visualization/{VisualizationID}:
put:
tags:
- visualizations
summary: Update properties of Visualization with ID VisualizationID
operationId: 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:
400:
description: PUT Unknown Visualization
content: {}
500:
description: Unable to save Visualization
content: {}
get:
tags:
- visualizations
summary: Get properties of Visualization with ID VisualizationID
operationId: getVisualizationProperties
parameters:
- in: path
name: VisualizationID
description: ID of a Visualization
required: true
schema:
type: integer
responses:
200:
description: Visualization received successfully (TODO CHECK CODE)
content:
application/json:
schema:
$ref: '#/components/schemas/Visualization'
400:
description: GET Unknown Visualization
content: {}
delete:
tags:
- visualizations
summary: Delete Visualization with ID VisualizationID
operationId: deleteVisualization
parameters:
- in: path
name: VisualizationID
description: ID of a Visualization
required: true
schema:
type: integer
responses:
400:
description: DELETE Unknown Visualization or unable to find project
content: {}
500:
description: Unable to remove Visualization or Unable to save project
content: {}
components:
schemas:
Project:
required:
- Name
- SimulationID
- UserID
type: object
properties:
Name:
type: string
UserID:
type: integer
User:
$ref: '#/components/schemas/User'
SimulationID:
type: integer
Simulation:
$ref: '#/components/schemas/Simulation'
Visualizations:
type: array
items:
$ref: '#/components/schemas/Visualization'
Visualization:
required:
- Name
- Grid
- ProjectID
- UserID
type: object
properties:
Name:
type: string
Grid:
type: integer
UserID:
type: integer
User:
$ref: '#/components/schemas/User'
ProjectID:
type: integer
Project:
$ref: '#/components/schemas/Project'
Widgets:
type: array
items:
$ref: '#/components/schemas/Widget'
User:
required:
- Username
- Password
- Role
- Mail
type: object
properties:
Username:
type: string
Password:
type: string
Role:
type: string
Mail:
type: string
Projects:
type: array
items:
$ref: '#/components/schemas/Project'
Simulations:
type: array
items:
$ref: '#/components/schemas/Simulation'
Files:
type: array
items:
$ref: '#/components/schemas/File'
Simulation:
required:
- Name
- UserID
type: object
properties:
Name:
type: string
Running:
type: boolean
Models:
type: array
items:
$ref: '#/components/schemas/SimulationModel'
Projects:
type: array
items:
$ref: '#/components/schemas/Project'
UserID:
type: integer
User:
$ref: '#/components/schemas/User'
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
User:
$ref: '#/components/schemas/User'
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: {}
SimulationModel:
required:
- Name
- OutputLength
- InputLength
- BelongsToSimulationID
- BelongsToSimulatorID
type: object
properties:
Name:
type: string
OutputLength:
type: integer
InputLength:
type: integer
BelongsToSimulationID:
type: integer
BelongsToSimulation:
$ref: '#/components/schemas/Simulation'
BelongsToSimulatorID:
type: integer
BelongsToSimulator:
$ref: '#/components/schemas/Simulator'
StartParameters:
type: object
properties: {}
OutputMapping:
type: array
items:
$ref: '#/components/schemas/Signal'
InputMapping:
type: array
items:
$ref: '#/components/schemas/Signal'
Signal:
required:
- Name
- Unit
- SimulationModelID
type: object
properties:
Name:
type: string
Unit:
type: string
SimulationModelID:
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: {}