Using the Web Service Interface

Communication

The API can be accessed over HTTP or HTTPS. In a production environment it is highly recommended to use HTTPS because otherwise primary credentials are transmitted in plaintext.

Authentication

For authentication we use OAuth 2.0 Resource Owner Password Credentials Grant (RFC 6749). In order to access a resource of the Web Service Interface the Client needs a valid access token and a valid session within the system. In case no token is presented, or the token is invalid (e.g. expired) or the system session is not available, the user will get a status code 401 Unauthorized and needs to request an access token. The access token can be requested through a dedicated resource (/token) by presenting the primary credentials. In case the credentials are provided, the system creates a new session and returns an access token.

Authentication flow:

1. Client tries to access a resource.
2. Server responds with status code 401 Unauthorized.
3. Client asks the end-user for credentials.
4. Client sends credentials to a dedicated resource.
5. Server returns an access token; the system creates an internal session.
6. Client again tries to access a resource and includes the access token in an authorization header.
7. Server returns content with status code 200 OK.

Subscriptions (Notifications with SignalR)

Optionally, for specified services the API provides not only data on request (pull) but also in case of an event determined by the respective service (push). Any Client subscribing for any push notifications needs to support SignalR (see SignalR documentation).

The Client first needs to connect to a dedicated SignalR hub and can then subscribe for notifications by providing a connection ID which it gets after a connection between Client and server is established. The Client then needs to implement a function (see signature in respective service chapters) which will be called from the server in case a notification is due.