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:

https://datacenter.dashboard.bernard-gruppe.com/api_v2/

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:

curl -X GET -H "Authorization: Bearer 0123456789" 
https://datacenter.dashboard.bernard-gruppe.com/api_v2/parkingsites

Example requests:

s.get(url="https://datacenter.dashboard.bernard-gruppe.com/api_v2/parkingsites", headers={"Authorization": "Bearer 0123456789"})

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.

GET /parkingsites

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.

GET parkingsite/example-site

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.

GET parkingsite/example-site/details

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.

GET /acoustics

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.

GET acoustic/example-station?from=2021-01-01T00:00:00.00&to=2021-01-01T01:00:00.00

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.

GET /directions

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.

GET direction/example-street?from=1970-01-01T00:00:00&to=1970-01-01T23:59:59

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.