VILLASweb Backend API (2.0)

Download OpenAPI specification:Download

This is the API of the VILLASweb Backend WORK IN PROGRESS! PLEASE BE PATIENT! The tool https://github.com/swaggo/swag is used to auto-generate API docs for gin.

authentication

Authentication for user

Request Body schema: application/json

loginRequest of user

Password
required
string
Username
required
string

Responses

200

JSON web token, success status, message and authenticated user object

401

Unauthorized

500

Internal server error.

post /authenticate
https://localhost:4000/api/v2/authenticate

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "Password": "string",
  • "Username": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "message": "string",
  • "success": true,
  • "token": "string",
  • "user":
    {
    }
}

dashboards

Get all dashboards of scenario

query Parameters
scenarioID
required
integer

Scenario ID

Responses

200

Dashboards which belong to scenario

404

Not found

422

Unprocessable entity

500

Internal server error

get /dashboards
https://localhost:4000/api/v2/dashboards

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "dashboards":
    [
    ]
}

Add a dashboard to a scenario

Request Body schema: application/json

Dashboard to be added incl. ID of Scenario

Grid
required
integer
Name
required
string
ScenarioID
required
integer

Responses

200

Dashboard that was added

400

Bad request

404

Not found

422

Unprocessable entity

500

Internal server error

post /dashboards
https://localhost:4000/api/v2/dashboards

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "Grid": 0,
  • "Name": "string",
  • "ScenarioID": 0
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "dashboard":
    {
    }
}

Get a dashboard

path Parameters
dashboardID
required
integer

Dashboard ID

Responses

200

Dashboard that was requested

400

Bad request

404

Not found

422

Unprocessable entity

500

Internal server error

get /dashboards/{dashboardID}
https://localhost:4000/api/v2/dashboards/{dashboardID}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "dashboard":
    {
    }
}

Update a dashboard

path Parameters
dashboardID
required
integer

Dashboard ID

Request Body schema: application/json

Dashboard to be updated

Grid
integer
Name
string

Responses

200

Dashboard that was updated

400

Bad request

404

Not found

422

Unprocessable entity

500

Internal server error

put /dashboards/{dashboardID}
https://localhost:4000/api/v2/dashboards/{dashboardID}

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "Grid": 0,
  • "Name": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "dashboard":
    {
    }
}

Delete a dashboard

path Parameters
dashboardID
required
integer

Dashboard ID

Responses

200

Dashboard that was deleted

400

Bad request

404

Not found

422

Unprocessable entity

500

Internal server error

delete /dashboards/{dashboardID}
https://localhost:4000/api/v2/dashboards/{dashboardID}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "dashboard":
    {
    }
}

files

Get all files of a specific model or widget

query Parameters
objectType
required
string

Set to model for files of model, set to widget for files of widget

objectID
required
integer

ID of either model or widget of which files are requested

Responses

200

Files which belong to simulation model or widget

404

Not found

422

Unprocessable entity

500

Internal server error

get /files
https://localhost:4000/api/v2/files

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "files":
    [
    ]
}

Add a file to a specific model or widget

query Parameters
objectType
required
string

Set to model for files of model, set to widget for files of widget

objectID
required
integer

ID of either model or widget of which files are requested

Request Body schema: application/x-www-form-urlencoded
inputFile
required
string <binary>

File to be uploaded

Responses

200

File that was added

400

Bad request

404

Not found

422

Unprocessable entity

500

Internal server error

post /files
https://localhost:4000/api/v2/files

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "file":
    {
    }
}

Download a file

path Parameters
fileID
required
integer

ID of the file to download

Responses

200

File that was requested

400

Bad request

404

Not found

422

Unprocessable entity

500

Internal server error

get /files/{fileID}
https://localhost:4000/api/v2/files/{fileID}

Update a file

path Parameters
fileID
required
integer

ID of the file to update

Request Body schema: application/x-www-form-urlencoded
inputFile
required
string <binary>

File to be uploaded

Responses

200

File that was updated

400

Bad request

404

Not found

422

Unprocessable entity

500

Internal server error

put /files/{fileID}
https://localhost:4000/api/v2/files/{fileID}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "file":
    {
    }
}

Delete a file

path Parameters
fileID
required
integer

ID of the file to update

Responses

200

File that was deleted

400

Bad request

404

Not found

422

Unprocessable entity

500

Internal server error

delete /files/{fileID}
https://localhost:4000/api/v2/files/{fileID}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "file":
    {
    }
}

models

Get all simulation models of scenario

query Parameters
scenarioID
required
integer

Scenario ID

Responses

200

Simulation models which belong to scenario

404

Not found

422

Unprocessable entity

500

Internal server error

get /models
https://localhost:4000/api/v2/models

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "models":
    [
    ]
}

Add a simulation model to a scenario

Request Body schema: application/json

Simulation model to be added incl. IDs of scenario and simulator

Name
required
string
ScenarioID
required
integer
SimulatorID
required
integer
StartParameters
required
string

Responses

200

simulation model that was added

400

Bad request

404

Not found

422

Unprocessable entity

500

Internal server error

post /models
https://localhost:4000/api/v2/models

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "Name": "string",
  • "ScenarioID": 0,
  • "SimulatorID": 0,
  • "StartParameters": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "model":
    {
    }
}

Get a simulation model

path Parameters
modelID
required
integer

Model ID

Responses

200

simulation model that was requested

400

Bad request

404

Not found

422

Unprocessable entity

500

Internal server error

get /models/{modelID}
https://localhost:4000/api/v2/models/{modelID}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "model":
    {
    }
}

Update a simulation model

path Parameters
modelID
required
integer

Model ID

Request Body schema: application/json

Simulation model to be updated

Name
string
SimulatorID
integer
StartParameters
string

Responses

200

simulation model that was added

400

Bad request

404

Not found

422

Unprocessable entity

500

Internal server error

put /models/{modelID}
https://localhost:4000/api/v2/models/{modelID}

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "Name": "string",
  • "SimulatorID": 0,
  • "StartParameters": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "model":
    {
    }
}

Delete a simulation model

path Parameters
modelID
required
integer

Model ID

Responses

200

simulation model that was deleted

400

Bad request

404

Not found

422

Unprocessable entity

500

Internal server error

delete /models/{modelID}
https://localhost:4000/api/v2/models/{modelID}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "model":
    {
    }
}

scenarios

Get all scenarios of requesting user

Responses

200

Scenarios to which user has access

404

Not found

422

Unprocessable entity

500

Internal server error

get /scenarios
https://localhost:4000/api/v2/scenarios

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "scenarios":
    [
    ]
}

Add a scenario

Request Body schema: application/json

Scenario to be added

Name
required
string
Running
boolean
StartParameters
required
string

Responses

200

scenario that was added

400

Bad request

404

Not found

422

Unprocessable entity

500

Internal server error

post /scenarios
https://localhost:4000/api/v2/scenarios

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "Name": "string",
  • "Running": true,
  • "StartParameters": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "scenario":
    {
    }
}

Get scenario

path Parameters
scenarioID
required
integer

Scenario ID

Responses

200

Scenario requested by user

404

Not found

422

Unprocessable entity

500

Internal server error

get /scenarios/{scenarioID}
https://localhost:4000/api/v2/scenarios/{scenarioID}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "scenario":
    {
    }
}

Update a scenario

path Parameters
scenarioID
required
integer

Scenario ID

Request Body schema: application/json

Scenario to be updated

Name
string
Running
boolean
StartParameters
string

Responses

200

Updated scenario.

400

Bad request

404

Not found

422

Unprocessable entity

500

Internal server error

put /scenarios/{scenarioID}
https://localhost:4000/api/v2/scenarios/{scenarioID}

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "Name": "string",
  • "Running": true,
  • "StartParameters": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "scenario":
    {
    }
}

Delete a scenario

path Parameters
scenarioID
required
integer

Scenario ID

Responses

200

Deleted scenario

404

Not found

422

Unprocessable entity

500

Internal server error

delete /scenarios/{scenarioID}
https://localhost:4000/api/v2/scenarios/{scenarioID}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "scenario":
    {
    }
}

Add a user to a a scenario

path Parameters
scenarioID
required
integer

Scenario ID

query Parameters
username
required
string

User name

Responses

200

User that was added to scenario

404

Not found

422

Unprocessable entity

500

Internal server error

put /scenarios/{scenarioID}/user
https://localhost:4000/api/v2/scenarios/{scenarioID}/user

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "user":
    {
    }
}

Delete a user from a scenario

path Parameters
scenarioID
required
integer

Scenario ID

query Parameters
username
required
string

User name

Responses

200

User that was deleted from scenario

404

Not found

422

Unprocessable entity

500

Internal server error

delete /scenarios/{scenarioID}/user
https://localhost:4000/api/v2/scenarios/{scenarioID}/user

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "user":
    {
    }
}

Get users of a scenario

path Parameters
scenarioID
required
integer

Scenario ID

Responses

200

Array of users that have access to the scenario

404

Not found

422

Unprocessable entity

500

Internal server error

get /scenarios/{scenarioID}/users/
https://localhost:4000/api/v2/scenarios/{scenarioID}/users/

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "users":
    [
    ]
}

signals

Get all signals of one direction

query Parameters
direction
required
string

Direction of signal (in or out)

modelID
required
string

Model ID of signals to be obtained

Responses

200

Signals which belong to simulation model

404

Not found

422

Unprocessable entity

500

Internal server error

get /signals
https://localhost:4000/api/v2/signals

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "signals":
    [
    ]
}

Add a signal to a signal mapping of a model

Request Body schema: application/json

A signal to be added to the model incl. direction and model ID to which signal shall be added

Direction
required
string
Index
required
integer
Name
required
string
SimulationModelID
required
integer
Unit
string

Responses

200

Signal that was added

400

Bad request

404

Not found

422

Unprocessable entity

500

Internal server error

post /signals
https://localhost:4000/api/v2/signals

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "Direction": "string",
  • "Index": 0,
  • "Name": "string",
  • "SimulationModelID": 0,
  • "Unit": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "signal":
    {
    }
}

Get a signal

path Parameters
signalID
required
integer

ID of signal to be obtained

Responses

200

Signal that was requested

400

Bad request

404

Not found

422

Unprocessable entity

500

Internal server error

get /signals/{signalID}
https://localhost:4000/api/v2/signals/{signalID}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "signal":
    {
    }
}

Update a signal

path Parameters
signalID
required
integer

ID of signal to be updated

Request Body schema: application/json

A signal to be updated

Index
integer
Name
string
Unit
string

Responses

200

Signal that was updated

400

Bad request

404

Not found

422

Unprocessable entity

500

Internal server error

put /signals/{signalID}
https://localhost:4000/api/v2/signals/{signalID}

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "Index": 0,
  • "Name": "string",
  • "Unit": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "signal":
    {
    }
}

Delete a signal

path Parameters
signalID
required
integer

ID of signal to be deleted

Responses

200

Signal that was deleted

400

Bad request

404

Not found

422

Unprocessable entity

500

Internal server error

delete /signals/{signalID}
https://localhost:4000/api/v2/signals/{signalID}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "signal":
    {
    }
}

simulators

Get all simulators

Responses

200

Simulators requested

404

Not found

422

Unprocessable entity

500

Internal server error

get /simulators
https://localhost:4000/api/v2/simulators

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "simulators":
    [
    ]
}

Add a simulator

Request Body schema: application/json

Simulator to be added

Host
required
string
Modeltype
required
string
Properties
required
string
State
string
UUID
required
string

Responses

200

Simulator that was added

400

Bad request

404

Not found

422

Unprocessable entity

500

Internal server error

post /simulators
https://localhost:4000/api/v2/simulators

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "Host": "string",
  • "Modeltype": "string",
  • "Properties": "string",
  • "State": "string",
  • "UUID": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "simulator":
    {
    }
}

Get simulator

path Parameters
simulatorID
required
integer

Simulator ID

Responses

200

Simulator that was requested

400

Bad request

404

Not found

422

Unprocessable entity

500

Internal server error

get /simulators/{simulatorID}
https://localhost:4000/api/v2/simulators/{simulatorID}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "simulator":
    {
    }
}

Update a simulator

path Parameters
simulatorID
required
integer

Simulator ID

Request Body schema: application/json

Simulator to be updated

Host
string
Modeltype
string
Properties
string
State
string
UUID
string

Responses

200

Simulator that was updated

400

Bad request

404

Not found

422

Unprocessable entity

500

Internal server error

put /simulators/{simulatorID}
https://localhost:4000/api/v2/simulators/{simulatorID}

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "Host": "string",
  • "Modeltype": "string",
  • "Properties": "string",
  • "State": "string",
  • "UUID": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "simulator":
    {
    }
}

Delete a simulator

path Parameters
simulatorID
required
integer

Simulator ID

Responses

200

Simulator that was deleted

400

Bad request

404

Not found

422

Unprocessable entity

500

Internal server error

delete /simulators/{simulatorID}
https://localhost:4000/api/v2/simulators/{simulatorID}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "simulator":
    {
    }
}

Get all simulation models in which the simulator is used

path Parameters
simulatorID
required
integer

Simulator ID

Responses

200

Simulation models requested by user

400

Bad request

404

Not found

422

Unprocessable entity

500

Internal server error

get /simulators/{simulatorID}/models
https://localhost:4000/api/v2/simulators/{simulatorID}/models

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "models":
    [
    ]
}

AMQP

Send an action to simulator (only available if backend server is started with -amqp parameter)

path Parameters
simulatorID
required
integer

Simulator ID

query Parameters
inputAction
required
string

Action for simulator

Responses

200

Action sent successfully

400

Bad request

404

Not found

422

Unprocessable entity

500

Internal server error

post /simulators/{simulatorID}/action
https://localhost:4000/api/v2/simulators/{simulatorID}/action

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "message": "string",
  • "success": true
}

users

Get all users

Responses

200

Array of users

404

Not found

422

Unprocessable entity

500

Internal server error

get /users
https://localhost:4000/api/v2/users

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "users":
    [
    ]
}

Add a user

Request Body schema: application/json

User to be added

Mail
required
string
Password
required
string
Role
required
string
Username
required
string

Responses

200

Contains added user object

400

Bad request

422

Unprocessable entity

500

Internal server error

post /users
https://localhost:4000/api/v2/users

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "Mail": "string",
  • "Password": "string",
  • "Role": "string",
  • "Username": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "user":
    {
    }
}

Get user

path Parameters
userID
required
integer

User ID

Responses

200

requested user

403

Access forbidden.

404

Not found

422

Unprocessable entity

500

Internal server error

get /users/{userID}
https://localhost:4000/api/v2/users/{userID}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "user":
    {
    }
}

Update a user

path Parameters
userID
required
integer

User ID

Request Body schema: application/json

User to be updated (anything except for ID can be changed, role can only be change by admin)

Active
string
Mail
string
Password
string
Role
string
Username
string

Responses

200

Contains updated user

400

Bad request.

403

Access forbidden.

404

Not found

422

Unprocessable entity

500

Internal server error

put /users/{userID}
https://localhost:4000/api/v2/users/{userID}

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "Active": "string",
  • "Mail": "string",
  • "Password": "string",
  • "Role": "string",
  • "Username": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "user":
    {
    }
}

Delete a user

path Parameters
userID
required
integer

User ID

Responses

200

deleted user

404

Not found

422

Unprocessable entity

500

Internal server error

delete /users/{userID}
https://localhost:4000/api/v2/users/{userID}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "user":
    {
    }
}

widgets

Get all widgets of dashboard

query Parameters
dashboardID
required
integer

Dashboard ID

Responses

200

Widgets to which belong to dashboard

404

Not found

422

Unprocessable entity

500

Internal server error

get /widgets
https://localhost:4000/api/v2/widgets

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "widgets":
    [
    ]
}

Add a widget to a dashboard

Request Body schema: application/json

Widget to be added incl. ID of dashboard

CustomProperties
string
DashboardID
required
integer
Height
required
integer
IsLocked
boolean
MinHeight
integer
MinWidth
integer
Name
required
string
Type
required
string
Width
required
integer
X
integer
Y
integer
Z
integer

Responses

200

Widget that was added

400

Bad request

404

Not found

422

Unprocessable entity

500

Internal server error

post /widgets
https://localhost:4000/api/v2/widgets

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "CustomProperties": "string",
  • "DashboardID": 0,
  • "Height": 0,
  • "IsLocked": true,
  • "MinHeight": 0,
  • "MinWidth": 0,
  • "Name": "string",
  • "Type": "string",
  • "Width": 0,
  • "X": 0,
  • "Y": 0,
  • "Z": 0
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "widget":
    {
    }
}

Get a widget

path Parameters
widgetID
required
integer

Widget ID

Responses

200

Widget that was requested

400

Bad request

404

Not found

422

Unprocessable entity

500

Internal server error

get /widgets/{widgetID}
https://localhost:4000/api/v2/widgets/{widgetID}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "widget":
    {
    }
}

Update a widget

path Parameters
widgetID
required
integer

Widget ID

Request Body schema: application/json

Widget to be updated

CustomProperties
string
Height
integer
IsLocked
boolean
MinHeight
integer
MinWidth
integer
Name
string
Type
string
Width
integer
X
integer
Y
integer
Z
integer

Responses

200

Widget that was updated

400

Bad request

404

Not found

422

Unprocessable entity

500

Internal server error

put /widgets/{widgetID}
https://localhost:4000/api/v2/widgets/{widgetID}

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "CustomProperties": "string",
  • "Height": 0,
  • "IsLocked": true,
  • "MinHeight": 0,
  • "MinWidth": 0,
  • "Name": "string",
  • "Type": "string",
  • "Width": 0,
  • "X": 0,
  • "Y": 0,
  • "Z": 0
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "widget":
    {
    }
}

Delete a widget

path Parameters
widgetID
required
integer

Widget ID

Responses

200

Widget that was deleted

400

Bad request

404

Not found

422

Unprocessable entity

500

Internal server error

delete /widgets/{widgetID}
https://localhost:4000/api/v2/widgets/{widgetID}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "widget":
    {
    }
}