VILLASweb Backend API (2.0)

Download OpenAPI specification:Download

Sonja Happ: sonja.happ@eonerc.rwth-aachen.de License: GNU GPL 3.0

This is the VILLASweb backend API v2.0. This documentation is auto-generated based on the API documentation in the code. The tool swag is used to auto-generate API docs for the gin-gonic framework. Authentication: Use the authenticate endpoint below to obtain a token for your user account, copy the token into to the value field of the dialog showing up for the green Authorize button below and confirm with Done.

authentication

Check if user is authenticated and provide details on how the user can authenticate

Responses

Response samples

200
401
500

Content type

application/json

{ }

Authentication for user

path Parameters

mechanism

required

string

Enum: "internal" "external"

Login mechanism

Request Body schema: application/json

loginRequest of user

Password required	string
Username required	string

Responses

Request samples

Payload

Content type

application/json

{"Password": "string",
"Username": "string"
}

Response samples

200
401
500

Content type

application/json

{ }

config

Get config VILLASweb to be used by frontend

Responses

Response samples

200

Content type

application/json

{"Providers": [{ }
]
}

component-configurations

Get all component configurations of scenario

Authorizations:

Bearer

query Parameters

scenarioID

required

integer

Scenario ID

Responses

Response samples

200
404
422
500

Content type

application/json

{ }

Add a component configuration to a scenario

Authorizations:

Bearer

Request Body schema: application/json

component configuration to be added incl. IDs of scenario and IC

object (component_configuration.validNewConfig)

FileIDs	Array of integers
ICID required	integer
Name required	string
ScenarioID required	integer
required	object (postgres.Jsonb)

Responses

Request samples

Payload

Content type

application/json

{"config": {"FileIDs": [0
],
"ICID": 0,
"Name": "string",
"ScenarioID": 0,
"StartParameters": {"json.RawMessage": [0
]
}
}
}

Response samples

200
400
404
422
500

Content type

application/json

{ }

Get a component configuration

Authorizations:

Bearer

path Parameters

configID

required

integer

Config ID

Responses

Response samples

200
400
404
422
500

Content type

application/json

{ }

Update a component configuration

Authorizations:

Bearer

path Parameters

configID

required

integer

Config ID

Request Body schema: application/json

component configuration to be updated

object (component_configuration.validUpdatedConfig)

FileIDs	Array of integers
ICID	integer
Name	string
	object (postgres.Jsonb)

Responses

Request samples

Payload

Content type

application/json

{"config": {"FileIDs": [0
],
"ICID": 0,
"Name": "string",
"StartParameters": {"json.RawMessage": [0
]
}
}
}

Response samples

200
400
404
422
500

Content type

application/json

{ }

Delete a component configuration

Authorizations:

Bearer

path Parameters

configID

required

integer

Config ID

Responses

Response samples

200
400
404
422
500

Content type

application/json

{ }

dashboards

Get all dashboards of scenario

Authorizations:

Bearer

query Parameters

scenarioID

required

integer

Scenario ID

Responses

Response samples

200
404
422
500

Content type

application/json

{ }

Add a dashboard to a scenario

Authorizations:

Bearer

Request Body schema: application/json

Dashboard to be added incl. ID of Scenario

object (dashboard.validNewDashboard)

Grid required	integer
Height	integer
Name required	string
ScenarioID required	integer

Responses

Request samples

Payload

Content type

application/json

{"dashboard": {"Grid": 0,
"Height": 0,
"Name": "string",
"ScenarioID": 0
}
}

Response samples

200
400
404
422
500

Content type

application/json

{ }

Get a dashboard

Authorizations:

Bearer

path Parameters

dashboardID

required

integer

Dashboard ID

Responses

Response samples

200
400
404
422
500

Content type

application/json

{ }

Update a dashboard

Authorizations:

Bearer

path Parameters

dashboardID

required

integer

Dashboard ID

Request Body schema: application/json

Dashboard to be updated

object (dashboard.validUpdatedDashboard)

grid	integer
height	integer
name	string

Responses

Request samples

Payload

Content type

application/json

{"dashboard": {"grid": 0,
"height": 0,
"name": "string"
}
}

Response samples

200
400
404
422
500

Content type

application/json

{ }

Delete a dashboard

Authorizations:

Bearer

path Parameters

dashboardID

required

integer

Dashboard ID

Responses

Response samples

200
400
404
422
500

Content type

application/json

{ }

files

Get all files of a specific scenario

Authorizations:

Bearer

query Parameters

scenarioID

required

integer

Scenario ID

Responses

Response samples

200
404
422
500

Content type

application/json

{ }

Add a file to a specific scenario

Authorizations:

Bearer

query Parameters

scenarioID

required

integer

ID of scenario to which file shall be added

Request Body schema:
text/plain

inputFile

required

string <binary>

File to be uploaded

Responses

Response samples

200
400
404
422
500

Content type

application/json

{ }

Download a file

Authorizations:

Bearer

path Parameters

fileID

required

integer

ID of the file to download

Responses

Update a file

Authorizations:

Bearer

path Parameters

fileID

required

integer

ID of the file to update

Request Body schema:
text/plain

inputFile

required

string <binary>

File to be uploaded

Responses

Response samples

200
400
404
422
500

Content type

application/json

{ }

Delete a file

Authorizations:

Bearer

path Parameters

fileID

required

integer

ID of the file to update

Responses

Response samples

200
400
404
422
500

Content type

application/json

{ }

healthz

Get health status of backend

Responses

Response samples

204
500

Content type

application/json

"string"

infrastructure-components

Get all infrastructure components

Authorizations:

Bearer

Responses

Response samples

200
404
422
500

Content type

application/json

{ }

Add an infrastructure component

Authorizations:

Bearer

Request Body schema: application/json

Infrastructure Component to be added

object (infrastructure_component.validNewIC)

APIURL	string
Category required	string
	object (postgres.Jsonb)
Description	string
Location	string
ManagedExternally required	boolean
Manager	string
Name required	string
	object (postgres.Jsonb)
State	string
	object (postgres.Jsonb)
Type required	string
UUID	string
Uptime	number
WebsocketURL	string

Responses

Request samples

Payload

Content type

application/json

{"ic": {"APIURL": "string",
"Category": "string",
"CreateParameterSchema": {"json.RawMessage": [0
]
},
"Description": "string",
"Location": "string",
"ManagedExternally": true,
"Manager": "string",
"Name": "string",
"StartParameterSchema": {"json.RawMessage": [0
]
},
"State": "string",
"StatusUpdateRaw": {"json.RawMessage": [0
]
},
"Type": "string",
"UUID": "string",
"Uptime": 0,
"WebsocketURL": "string"
}
}

Response samples

200
400
404
422
500

Content type

application/json

{ }

Get infrastructure component

Authorizations:

Bearer

path Parameters

ICID

required

integer

Infrastructure Component ID

Responses

Response samples

200
400
404
422
500

Content type

application/json

{ }

Update an infrastructure component

Authorizations:

Bearer

path Parameters

ICID

required

integer

InfrastructureComponent ID

Request Body schema: application/json

InfrastructureComponent to be updated

object (infrastructure_component.validUpdatedIC)

APIURL	string
Category	string
	object (postgres.Jsonb)
Description	string
Location	string
Manager	string
Name	string
	object (postgres.Jsonb)
State	string
	object (postgres.Jsonb)
Type	string
UUID	string
Uptime	number
WebsocketURL	string

Responses

Request samples

Payload

Content type

application/json

{"ic": {"APIURL": "string",
"Category": "string",
"CreateParameterSchema": {"json.RawMessage": [0
]
},
"Description": "string",
"Location": "string",
"Manager": "string",
"Name": "string",
"StartParameterSchema": {"json.RawMessage": [0
]
},
"State": "string",
"StatusUpdateRaw": {"json.RawMessage": [0
]
},
"Type": "string",
"UUID": "string",
"Uptime": 0,
"WebsocketURL": "string"
}
}

Response samples

200
400
404
422
500

Content type

application/json

{ }

Delete an infrastructure component

Authorizations:

Bearer

path Parameters

ICID

required

integer

Infrastructure Component ID

Responses

Response samples

200
400
404
422
500

Content type

application/json

{ }

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

Authorizations:

Bearer

path Parameters

ICID

required

integer

InfrastructureComponent ID

query Parameters

inputAction

required

string

Action for IC

Responses

Response samples

200
400
404
422
500

Content type

application/json

{ }

Get all configurations of the infrastructure component

Authorizations:

Bearer

path Parameters

ICID

required

integer

Infrastructure Component ID

Responses

Response samples

200
400
404
422
500

Content type

application/json

{ }

metrics

Prometheus metrics endpoint

Responses

Response samples

200

Content type

application/json

"string"

openapi

Get OpenAPI 2.0 spec of API

Responses

Response samples

200

Content type

application/json

"string"

results

Get all results of scenario

Authorizations:

Bearer

query Parameters

scenarioID

required

integer

Scenario ID

Responses

Response samples

200
404
422
500

Content type

application/json

{ }

Add a result to a scenario

Authorizations:

Bearer

Request Body schema: application/json

Result to be added incl. ID of Scenario

object (result.validNewResult)

required	object (postgres.Jsonb)
Description	string
ResultFileIDs	Array of integers
ScenarioID required	integer

Responses

Request samples

Payload

Content type

application/json

{"result": {"ConfigSnapshots": {"json.RawMessage": [0
]
},
"Description": "string",
"ResultFileIDs": [0
],
"ScenarioID": 0
}
}

Response samples

200
400
404
422
500

Content type

application/json

{ }

Get a Result

Authorizations:

Bearer

path Parameters

resultID

required

integer

Result ID

Responses

Response samples

200
400
404
422
500

Content type

application/json

{ }

Update a result

Authorizations:

Bearer

path Parameters

resultID

required

integer

Result ID

Request Body schema: application/json

Result to be updated

object (result.validUpdatedResult)

	object (postgres.Jsonb)
description	string
resultFileIDs	Array of integers

Responses

Request samples

Payload

Content type

application/json

{"result": {"configSnapshots": {"json.RawMessage": [0
]
},
"description": "string",
"resultFileIDs": [0
]
}
}

Response samples

200
400
404
422
500

Content type

application/json

{ }

Delete a Result incl. all result files

Authorizations:

Bearer

path Parameters

resultID

required

integer

Result ID

Responses

Response samples

200
400
404
422
500

Content type

application/json

{ }

Upload a result file to the DB and associate it with scenario and result

Authorizations:

Bearer

path Parameters

resultID

required

integer

Result ID

Request Body schema:
text/plain

inputFile

required

string <binary>

File to be uploaded

Responses

Response samples

200
400
404
422
500

Content type

application/json

{ }

Delete a result file

Authorizations:

Bearer

path Parameters

resultID required	integer Result ID
fileID required	integer ID of the file to delete

Responses

Response samples

200
400
404
422
500

Content type

application/json

{ }

scenarios

Get all scenarios of requesting user

Authorizations:

Bearer

Responses

Response samples

200
404
422
500

Content type

application/json

{ }

Add a scenario

Authorizations:

Bearer

Request Body schema: application/json

Scenario to be added

object (scenario.validNewScenario)

Name required	string
required	object (postgres.Jsonb)

Responses

Request samples

Payload

Content type

application/json

{"scenario": {"Name": "string",
"StartParameters": {"json.RawMessage": [0
]
}
}
}

Response samples

200
400
404
422
500

Content type

application/json

{ }

Get scenario

Authorizations:

Bearer

path Parameters

scenarioID

required

integer

Scenario ID

Responses

Response samples

200
404
422
500

Content type

application/json

{ }

Update a scenario

Authorizations:

Bearer

path Parameters

scenarioID

required

integer

Scenario ID

Request Body schema: application/json

Scenario to be updated

object (scenario.validUpdatedScenario)

IsLocked	boolean
Name	string
	object (postgres.Jsonb)

Responses

Request samples

Payload

Content type

application/json

{"scenario": {"IsLocked": true,
"Name": "string",
"StartParameters": {"json.RawMessage": [0
]
}
}
}

Response samples

200
400
404
422
500

Content type

application/json

{ }

Delete a scenario

Authorizations:

Bearer

path Parameters

scenarioID

required

integer

Scenario ID

Responses

Response samples

200
404
422
500

Content type

application/json

{ }

Add a user to a a scenario

Authorizations:

Bearer

path Parameters

scenarioID

required

integer

Scenario ID

query Parameters

username

required

string

User name

Responses

Response samples

200
404
422
500

Content type

application/json

{ }

Delete a user from a scenario

Authorizations:

Bearer

path Parameters

scenarioID

required

integer

Scenario ID

query Parameters

username

required

string

User name

Responses

Response samples

200
404
422
500

Content type

application/json

{ }

Get users of a scenario

Authorizations:

Bearer

path Parameters

scenarioID

required

integer

Scenario ID

Responses

Response samples

200
404
422
500

Content type

application/json

{ }

signals

Get all signals of one direction

Authorizations:

Bearer

query Parameters

direction required	string Direction of signal (in or out)
configID required	string Config ID of signals to be obtained

Responses

Response samples

200
404
422
500

Content type

application/json

{ }

Add a signal to a signal mapping of a component configuration

Authorizations:

Bearer

Request Body schema: application/json

A signal to be added to the component configuration incl. direction and config ID to which signal shall be added

object (signal.validNewSignal)

ConfigID required	integer
Direction required	string
Index required	integer
Name required	string
ScalingFactor	number
Unit	string

Responses

Request samples

Payload

Content type

application/json

{"signal": {"ConfigID": 0,
"Direction": "string",
"Index": 0,
"Name": "string",
"ScalingFactor": 0,
"Unit": "string"
}
}

Response samples

200
400
404
422
500

Content type

application/json

{ }

Get a signal

Authorizations:

Bearer

path Parameters

signalID

required

integer

ID of signal to be obtained

Responses

Response samples

200
400
404
422
500

Content type

application/json

{ }

Update a signal

Authorizations:

Bearer

path Parameters

signalID

required

integer

ID of signal to be updated

Request Body schema: /

A signal to be updated

object (signal.validUpdatedSignal)

Index	integer
Name	string
ScalingFactor	number
Unit	string

Responses

Response samples

200
400
404
422
500

Content type

application/json

{ }

Delete a signal

Authorizations:

Bearer

path Parameters

signalID

required

integer

ID of signal to be deleted

Responses

Response samples

200
400
404
422
500

Content type

application/json

{ }

users

Get all users

Authorizations:

Bearer

Responses

Response samples

200
404
422
500

Content type

application/json

{ }

Add a user

Authorizations:

Bearer

Request Body schema: application/json

User to be added

object (user.validNewUser)

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

Responses

Request samples

Payload

Content type

application/json

{"user": {"Mail": "string",
"Password": "string",
"Role": "string",
"Username": "string"
}
}

Response samples

200
400
422
500

Content type

application/json

{ }

Get user

Authorizations:

Bearer

path Parameters

userID

required

integer

User ID

Responses

Response samples

200
403
404
422
500

Content type

application/json

{ }

Update a user

Authorizations:

Bearer

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)

object (user.validUpdatedRequest)

Active	string
Mail	string
OldPassword	string
Password	string
Role	string
Username	string

Responses

Request samples

Payload

Content type

application/json

{"user": {"Active": "string",
"Mail": "string",
"OldPassword": "string",
"Password": "string",
"Role": "string",
"Username": "string"
}
}

Response samples

Content type

application/json

{ }

Delete a user

Authorizations:

Bearer

path Parameters

userID

required

integer

User ID

Responses

Response samples

200
404
422
500

Content type

application/json

{ }

widgets

Get all widgets of dashboard

Authorizations:

Bearer

query Parameters

dashboardID

required

integer

Dashboard ID

Responses

Response samples

200
404
422
500

Content type

application/json

{ }

Add a widget to a dashboard

Authorizations:

Bearer

Request Body schema: application/json

Widget to be added incl. ID of dashboard

object (widget.validNewWidget)

	object (postgres.Jsonb)
DashboardID required	integer
Height required	integer
IsLocked	boolean
MinHeight	integer
MinWidth	integer
Name required	string
SignalIDs	Array of integers
Type required	string
Width required	integer
X	integer
Y	integer
Z	integer

Responses

Request samples

Payload

Content type

application/json

{"widget": {"CustomProperties": {"json.RawMessage": [0
]
},
"DashboardID": 0,
"Height": 0,
"IsLocked": true,
"MinHeight": 0,
"MinWidth": 0,
"Name": "string",
"SignalIDs": [0
],
"Type": "string",
"Width": 0,
"X": 0,
"Y": 0,
"Z": 0
}
}

Response samples

200
400
404
422
500

Content type

application/json

{ }

Get a widget

Authorizations:

Bearer

path Parameters

widgetID

required

integer

Widget ID

Responses

Response samples

200
400
404
422
500

Content type

application/json

{ }

Update a widget

Authorizations:

Bearer

path Parameters

widgetID

required

integer

Widget ID

Request Body schema: application/json

Widget to be updated

object (widget.validUpdatedWidget)

	object (postgres.Jsonb)
Height	integer
IsLocked	boolean
MinHeight	integer
MinWidth	integer
Name	string
SignalIDs	Array of integers
Type	string
Width	integer
X	integer
Y	integer
Z	integer

Responses

Request samples

Payload

Content type

application/json

{"widget": {"CustomProperties": {"json.RawMessage": [0
]
},
"Height": 0,
"IsLocked": true,
"MinHeight": 0,
"MinWidth": 0,
"Name": "string",
"SignalIDs": [0
],
"Type": "string",
"Width": 0,
"X": 0,
"Y": 0,
"Z": 0
}
}

Response samples

200
400
404
422
500

Content type

application/json

{ }

Delete a widget

Authorizations:

Bearer

path Parameters

widgetID

required

integer

Widget ID

Responses

Response samples

200
400
404
422
500

Content type

application/json

{ }