Der Auruf der REST-Schnittstellen erfolgt nach einem einheitlichen Prinzip. Dieser Ansatz vereinfacht die Implementierung.

Inhaltsverzeichnis

1 Request
2 Authentifizierung
- 2.1 Token
3 REST-Anfrage an Dienst
4 Fehlerbehandlung

Request

Der Aufruf der REST-Schnittstelle ähnelt bei jedem OSB-Dienst und hat folgenden Aufbau der URL:

https://www.websale.de/api/SERVICEID/ACTION

Parameter	Bedeutung

Parameter

Bedeutung

SERVICEID

Stellt den OSB-Dienst dar. Dies ist nicht notwendigerweise die AppID des Dienstes.

Beispiele: emm, hreflangCollector, images, pagespeedtool, websaleapp2, usw.

ACTION

Wird dem OSB-Dienst als Parameter übergeben und der Dienst kann dann entsprechend reagieren.

Wenn ein Dienst eine Aktion nicht kennt, sollte immer ein HTTP-Fehlercode 400 (Bad Request) zurückgegeben werden.

Beispiele: changeemail, start, cancel, publish, build, send, usw.

Authentifizierung

Es ist bei jedem OSB-Dienst wichtig, dass der User sich zuerst authentifiziert und dem Aufruf einen Token mitgibt. Wie ein Token beim Authentserver erzeugt wird, ist in der Dokumentation "REST Authentifizierung" beschrieben:

REST-Authentifizierung

Token

Der Token ist ein “JSON Web Token” (JWT) und besteht aus 3 Teilen:

Header: Hier steht, mit welchem Algorithmus die Signatur verschlüsselt ist sowie die Art des Token.
Payload: Hier stehen alle Informationen, die bei einem CGI-Aufruf im Context stehen. Zusätzlich ist ein Timestamp enthalten, der angibt, wie lang der Token gültig ist.
Signatur: Die Signatur ist ein verschlüsselter Hash, der aus dem Header und dem Payload besteht. Das dazugehörige Passwort steht in der dbcgi.cfg unter Global → RestPassword.

Für weitere Informationen zu JWT kann die offizielle Webseite besucht werden: https://jwt.io

Der generierte Token ist nur für einen Zeitraum von 30 Minuten gültig. Sobald dieser nicht mehr gültig ist, geben alle Anfragen den Statuscode 401 zurück. Ist dies der Fall muss ein neuer Token generiert werden.

REST-Anfrage an Dienst

Jeder Dienst mit einer REST-Schnittstelle muss über eine spezielle REST-kompatible URL aufrufbar sein.

Dieser Aufruf verweist auf die entsprechende CGI. Zudem muss im Request-Header zusätzlich der Token angegeben werden.

X-Authorization: Bearer TOKEN

Fehlerbehandlung

Wenn ein Problem entsteht, muss ein zum Vorfall passender HTTP-Code zurückgegeben werden.

So muss immer der HTTP-Code 401 zurückgegeben werden, wenn der User auf eine Ressource ohne einen gültigen Token zugreifen möchte.