Interseroh EntsorgerPortal API

Allgemeine Beschreibung

Technologien

Restful API

• Es wird das Programmierparadigma REST eingesetzt.
• https://de.wikipedia.org/wiki/Representational_State_Transfer

JSON

• Es wird das Datenformat JSON eingesetzt.
• https://de.wikipedia.org/wiki/JavaScript_Object_Notation

Swagger

Zur technischen Dokumentation der einzelnen Services wird das Tool Swagger eingesetzt ( Link zur technischen Dokumentation). Es liefert für jeden Service folgende Informationen:

Endpoint

• URL
• HTTP Methode
• Funktion

Request

• Modell
• DTO
• Parameter

Response

• Modell
• Content Type
• HTTP Status

Zusätzlich können hier über eine Oberfläche Requests an die einzelnen Services getestet werden.

Registrierung

Aktuell befinden sich alle Services noch in der Pilotphase. Während dieser Phase findet die Registrierung nach Absprache zwischen Interseroh und den Pliotpartnern statt. Beim Übergang in den Regelbetrieb wird eine Webapplikation zur Registierung bereitgestellt werden.

Authentifizierung

Die Authentifizierung erfolgt nach dem Authorization Framework OAuth2 (siehe Quellen). Jeder Servicerequest muss durch ein entsprechendes Access Token authentifiziert werden. Ein solches Token wird über einen Authorization Server bereitgestellt. Es wird JWT Token verwendet.

Quellen

• Spezifikationen: https://tools.ietf.org/html/rfc6749
• Beschreibung: https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2
• JWT Token: https://jwt.io

Authorization Server

• Testsystem: https://www.interseroh-portal-test.com/openid-connect-server-webapp/token
• Produktivsystem: https://www.interseroh-portal.de/openid-connect-server-webapp/token

Credentials

Bei der Registrierung wird dem potentiellen API Consumer je ein client_id und client_secret mitgeteilt. Sie werden benötigt um ein Access Token anzufordern. Sie werden in Form eines Authorization Header übertragen. Dieser Header wird wie folgt erzeugt:

• 'Authorization: Basic ' + Base64( client_id + ':' + client_secret)
• Zum kodieren in Base64 kann beispielsweise diese Seite verwendet werden: https://www.base64encode.org
• z.B.: Authorization: Basic AbCdEfGhIyKlMnOpQrS==

Anfrage Access Token

Authorization Grant

Es wird der Authorization Grant Client Credentials verwendet.

HTTP Message

https://server.example.com/openid-connect-server-webapp/token
POST / HTTP/1.1
Host: server.example.com
Authorization: Basic AbCdEfGhIyKlMnOpQrS==
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials

CURL-Befehl

curl -XPOST -u [client_id]:[client_secret] https://www.interseroh-portal-test.com/openid-connect-server-webapp/token -d "grant_type=client_credentials"

Antwort mit Access Token

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
  "access_token":"feefdae9-61ef-434a-8e0c-85eab2dcb02a",
  "token_type":"bearer",
  "expires_in":1800,
}

Parameter

Die Bedeutung der einzelnen Parameter sind in der Spezifikation (siehe Quellen) beschrieben.

Antwort mit Error

{
  "status":401,
  "error":"Unauthorized",
  "message":"Error description ...",
  "path":"/openid-connect-server-webapp/token"
}