Betriebsanleitung (English)
1. Getting started
This document explains how to successfully call Bernard API with your app and receive data as result.
1.1 Specification
The Bernard API uses the REST software architectural style for operating HTTPS request and complies to the REST constraints. There is limitation to which constraints to use however, since we only allow request of data from a specified resource, GET method will be the preferred choice of request method. Every request starts with the following endpoint:
2. Authentication
For you to be able to authenticate yourself on our API, essential token authentication is needed. Token authentication (also called Bearer authentication) is an HTTP authentication scheme with security tokens. Any person carrying such tokens in their request is given access, therefore, you must send the received token in the Authorization header when making requests. Otherwise failure of identification will occur and communication will be hindered. Below are alternative ways to test your received token:
Example curl:
Example requests:
The logic behind using Bearer authentication is making API requests simpler, removing the necessity of cryptographic signing for each request and the involvement of complex libraries. The drawback is the requirement of an HTTPS connection as the request contains a plaintext token. All requests must therefore be secure, i.e. https and not http
3. Resources
All requests must be made with a proper integrated token authentication. Depending on your authentication, a number of endpoints will made available to you. Each endpoint showcases relevant information but a distinction is required to eliminate potential confusion. General endpoints are endpoints with plural naming that contains generic information, while the more specific endpoints with singular naming accommodate unique information.
3.1 Parking sites
The first request you make should be to acquire details over parking sites available to you.
3.1.1 Example Response
{
"node_id": 1,
"alias": "example-site",
"label": "example-label",
"timezone": "Europe/Berlin",
}
3.1.2 Parking Sites Object
Field
Type
Description
node_id
integer
A unique identifier for the user
alias
string
Name of parking site
label
string
Classifying name applied to the user
timezone
string
Time zone of the server
3.1.3 Possible Errors
Error Code
Description
400 Bad Request
Malformed bearer token, incorrect message framing.
401 Unauthorized
The bearer token is invalid or has been revoked.
404 Not Found
The request contains an incorrect URL.
405 Method not Allowed
Performing a certain action for the URL is not allowed.
500 Server Error
The server is incapable of performing the request.
3.2 Parking Site
Returns data that is related to the user.
3.2.1 Example Response
{
"id": 10,
"identifier": "example-site",
"maxParkingSpace": 100,
"dataTimezone": "Europe/Berlin",
"lon": null,
"lat": null,
"dataTimeUTC": "2021-01-01T00:00:00.00+00:00",
"usedParkingSpaces": 10
}
3.2.2 Parkingsite Object
Field
Type
Description
id
integer
A unique identifier for the parking site
identifier
string
The name of the parking site
maxParkingSpace
integer
Total capacity
dataTomezone
string
Time zone
Ion
integer
Longitude
Iat
integer
Latitude
dataTimeUTC
string
Date and time
usedParkingSpaces
integer
Number of occupied parking spaces
3.2.3 Possible Errors
Error Code
Description
400 Bad Request
Malformed bearer token, incorrect message framing.
401 Unauthorized
The bearer token is invalid or has been revoked.
403 Forbidden
The request attempts to list other client's nodes is forbidden.
404 Not Found
The request contains an incorrect URL.
405 Method not Allowed
Performing a certain action for the URL is not allowed.
3.3 Parking Detail
Displays information about each parking spot.
3.3.1 Example Response
{
"example-spot": {
"state": "occupied",
"since": "2021-01-01T00:00:00.00+00:00",
"center": {
"long": null,
"lat": null
}
}
}
3.3.2 Parkingsite Detail Object
Field
Type
Description
example-spot
string
Name of the parking spot
state
string
Status of the parking spot.
since
string
Last updated change for the parking spot
long
float
Longitude
Iat
float
Latitude
3.3.3 Possible errors
Error Code
Description
400 Bad Request
Malformed bearer token, incorrect message framing-
401 Unauthorized
The bearer token is invalid or has been revoked
403 Forbidden
The request attempts to list other client's nodes is forbidden.
404 Not Found
The request contains an incorrect URL.
405 Method not Allowed
Performing a certain action for the URL is not allowed.
3.4 Acoustics
The first request you make should be to acquire details over acoustic stations available to you.
3.4.1 Example Response
{
"node_id": 1,
"alias": "example-station",
"hosts": [
{
"count":100,
"name": "sensor"
}
],
"timezone": "Europe/Berlin"
}
3.4.2 Acoustics Object
Field
Type
Description
node_id
integer
A unique identifier for the user
alias
string
Name of station
hosts
string
Contains the count of values ad the name of the host
timezone
string
Time zone of the server
3.4.3 Possible errors
Error Code
Description
400 Bad Request
Malformed bearer token, incorrect message framing.
401 Unauthorized
the bearer tolen is invalid or has been revoked.
404 Not Found
The request contains an incorrect URL.
405 Method not Allowed
Performing a certain action for the URL is not allowed.
500 Server Error
The server is incapable of performing the request.
3.5 Acoustic
Returns data that is related to the user with a specified time frame.
3.5.1 Example Response
{
"id": 10,
"user": "example-station",
"timeStamp": "1970-01-01T00:00:00",
"documents": []
}
3.5.2 Acoustic Object
Field
Type
Description
id
integer
A unique identifier
user
string
The name of the acoustic station
timeStamp
string
Date and time
documents
array
Containers of information from the acoustic station
3.5.3 Possible errors
Error Code
Description
400 Bad Request
Malformed bearer token, incorrect message framing.
401 Unauthorized
The bearer tolen is invalid or has been revoked.
403 Forbidden
The request attempts to list other client's nodes is forbidden.
404 Not Found
The request contains an incorrect URL.
405 Method not Allowed
Performing a certain action for the URL is not allowed.
3.6 Directions
The first request you make should be to acquire details over acoustic stations available to you.
3.6.1 Example response
{
"id": 1,
"alias": "example-street",
"fields": "street/direction"
}
3.6.2 Directions response
Field
Type
Description
id
integer
A unique identifier for the user
alias
string
Shortening of street name
fields
string
Street/Direction
3.6.3 Possible errors
Error Code
Description
400 Bad Request
Malformed bearer token, incorrect message framing.
401 Unauthorized
the bearer tolen is invalid or has been revoked.
404 Not Found
The request contains an incorrect URL.
405 Method not Allowed
Performing a certain action for the URL is not allowed.
500 Server Error
The server is incapable of performing the request.
3.7 Direction
Returns data that is related to the user with a specified time frame.
3.7.1 Example Response
{
"id": 10,
"direction": "street/direction",
"car": 0,
"car with trailer": 0,
"van": 0,
"single unit truck": 0,
"articulated truck": 0,
"truck with trailer": 0,
"bus": 0,
"motorbike": 0,
"bike": 0,
"person": 0,
"total": 0
}
3.7.2 Direction object
Field
Type
Description
id
integer
A unique identifier
direction
string
The name of the street or direction
vehicles
integer
Number of cars, wans, bus, etc.
total
integer
Total number of vehilces
3.7.3 Possible errors
Error Code
Description
400 Bad Request
Malformed bearer token, incorrect message framing.
401 Unauthorized
The bearer tolen is invalid or has been revoked.
403 Forbidden
The request attempts to list other client's nodes is forbidden.
404 Not Found
The request contains an incorrect URL.
405 Method not Allowed
Performing a certain action for the URL is not allowed.
Last updated