Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 10 Next »

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

Inhaltsverzeichnis

Aufruf (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

SERVICEID

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

ACTION

Wir dem OSB-Dienst als Parameter übergeben und der Dienst reagiert dann entsprechend reagieren.

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

Beim Aufruf der URL wird der entsprechende Dienst mit folgenden Parametern aufgerufen:

"isrest=yes&action=ACTION"

Damit die URL funktioniert, wird von der WEBSALE Technik eine entsprechende RewriteRule eingebunden:

<IfModule mod_rewrite.c>
	RewriteEngine on
	...
	RewriteCond %{QUERY_STRING} ^(.*)$
	RewriteRule ^/api/ID/(.*) /cgi/APP/APP.cgi?isrest=yes&action=$1&%1 [PT]
	...
</IfModule>

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:

  1. Header: Hier steht, mit welchem Algorithmus die Signatur verschlüsselt ist sowie die Art des Token.

  2. 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.

  3. 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

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.

Shopzugriff

Da auch Requests aus dem Shop ausgeführt werden, wird ein für den Zweck benötigter User existieren. Dieser User muss zwingend Adminberechtigungen haben.

Um Missbrauch vorzubeugen, muss dieses Konto spezielle Regeln befolgen:

  1. Das Konto darf nur vom internen System auf die REST-Schnittstelle zugreifen.

  2. Das Konto darf nur über das REST-Interface mit dem AuthentServer kommunizieren.

Damit die Regeln befolgt werden, muss eine Konfigurationsdatei rest.cfg erstellt werden, die folgende Sektion beinhaltet:

<+REST-User>
   PersNr = 0000000       # Personennummer des Users
   AllowBrowserLogin = no # yes/no, Flag ob Konto sich über Browser im OSB einloggen kann
   +IPAllowed = 123.123.123.123 # IP-Adresse über die Request erlaubt ist
   +IPAllowed = 123.123.124.*	# Möglich ein IP-Block anzugeben (* nur letzter Block möglich)
</+REST-User>

tt

  • No labels