Migration von SOAP zu REST Gateway

Mit der Umstellung des Gateway von SOAP auf REST sind einige technologische Änderungen verknüpft. Dieser Leitfaden soll etablierten Nutzern der SOAP-Schnittstelle helfen, den Umstieg auf die REST-Schnittstelle durchzuführen. Alle Daten, die am SOAP-Gateway angefragt werden können, werden grundlegend auch durch die REST-Schnittstelle geliefert.

Swagger

Die REST-Schnittstelle wird mittels swagger (OpenAPI) dokumentiert. Mittels SwaggerUI kann diese Dokumentation direkt im Browser eingesehen werden.

Jede Anfrage wird separat mit der erwarteten HTTP-Methode (GET, POST, DELETE etc.) angezeigt.
Ist bei einer Anfrage ein Schloss angegeben, muss dort ein Token zur Authentifizierung eingegeben werden (siehe Abschnitt Sicherheit/Authentifizierung).
Für die Anfrage werden angezeigt:
- erwartete Parameter der Anfrage
- Beispiele (Example Value) und Schema (Link neben Example Value) für die Anfrage (body)
- mögliche HTTP-Status für die Antwort vom Server
- Schema und Beispiele für die Antwort (body) je nach HTTP-Status
Über den Button kann eine Abfrage an den gewählten Server gesendet werden.
- Es wird eine Beispiel-Anfrage angezeigt, die verändert werden kann.
- Über den Button Execute wird die Anfrage an den ausgewählten Server gesendet.
- Die Antwort erscheint ebenfalls direkt im Browser.

Technische Änderungen

Sicherheit/Authentifizierung

Ein Login mittels BASIC-Authentifizierung ist nicht mehr möglich. Zur Authentifizierung muss einer Anfrage an das REST-Gateway ein gültiges Token (JWT, RFC 7519) beigefügt werden (Bearer Auth).

Die benötigten Daten zur Authentifizierung bleiben gleich:

ein "Alias-Nutzer" mit Name und Passwort
das API-Token, mit dem die Client-Anwendung identifiziert wird. Client-Anwendung berechtigt, im Auftrag des Alias-Nutzers zu handeln.

Serviceanbieter, die die Kommunikation mit Qualiproof im Auftrag eines Anwenders durchführen, müssen jeweils dessen Benutzerkennung und Kennwort verwenden. Wie für den Anwender selbst gilt auch für den Serviceanbieter die Sorgfaltspflicht beim der Aufbewahrung/Speicherung dieser Zugangsdaten.

Geändert ist der Ablauf, wie diese Zugangsdaten zum Gateway übertragen werden.

Mit einer Anfrage an POST /access-token werden die Daten geprüft. Bei Erfolg wird ein Token (JWT, String) mit begrenzter Gültigkeit erzeugt. Diese Anfrage benötigt keinen Authorization-Header.
Das erzeugte Token muss im HTTP-Header Authorization der Anfrage an das REST-Gateway stehen, um den Nutzer zu authentifizieren.
Beispiel: "Authorization: Bearer eyJ0e..."
Das Gateway kann Token ablehnen. Dies wird durch den HTTP-Statuscode 401 NOT AUTHORIZED signalisiert.

Die Client-Anwendung muss bei jeder Anfrage damit rechnen, dass die Authentifizierung abgelehnt wird. Es kann ausreichen ein neues Token zu erfragen und die Anfrage zu wiederholen. In einigen Fällen muss eine weitere Interaktion mit dem Nutzer erfolgen. Beispiele für abgelehnte Token:

Die Gültigkeit im Feld expIso (Datum mit Uhrzeit im ISO-Format) bzw. im Feld exp (Unixzeit) wurde erreicht. Das Token ist nach diesem Zeitpunkt ungültig. Die Ablaufzeiten können sich zukünftig ändern. Ein neues Token kann einfach über die Schnittstelle erzeugt werden.
Der Nutzer-Account wurde deaktiviert. Dies ist allein aus dem Token nicht feststellbar. Hier schlägt auch das Erzeugen eines neuen Token fehl.

Das Token kann mit gängigen JWT-Bibliotheken (siehe auch ↗ jwt.io/) inspiziert werden. Es ist ein Base64-codiertes JSON-Objekt. Es ist durch seine Signatur vor Manipulation geschützt. Der Server erstellt und akzeptiert nur signierte Token.

Datenaustausch mit JSON

Für die REST-Schnittstelle wird JSON als Austauschformat benutzt (siehe auch ↗ json.org).

Als Encoding/Zeichensatz für das JSON-Format ist gemäß Standard nur UTF-8 zulässig. Kann die gesendete Anfrage nicht als UTF-8 String gelesen werden, wird sie mit HTTP-Status 400 BAD REQUEST abgelehnt. Der Gateway sendet alle JSON-Antworten ebenfalls in UTF-8 Encoding.

Probleme mit dem Encoding der Antwort äußern sich durch falsch dargestellte Umlaute oder Sonderzeichen. Verwendet die Client-Anwendung einen anderen Zeichsatz als UTF-8 (verbreitet ist z.B. Windows-1252), muss beim Senden der Anfrage und Empfangen der Antwort darauf geachtet werden, dass die gesendeten Daten mit dem richtigen Zeichensatz verarbeitet werden.

Transportsicherheit (SSL)

Alle Anfragen müssen über SSL (https) durchgeführt werden. Dadurch werden die Daten während der Übertragung verschlüsselt.

Datentypen

Für primitive Datentypen (Zeichenketten, Zahlen, Booleans) werden die definierten JSON-Datentypen genutzt. null -Werte werden durch Weglassen des entsprechenden Parameters abgehandelt. Für komplexe Datentypen gilt:

Datum (`date`)	String im ISO-Format `yyyy-MM-dd`
Datum mit Uhrzeit (`date-time`)	String im ISO-Format `yyyy-MM-dd'T'HH:mm:ss`
Zeitraum (`period`)	String im Format `dateFrom/dateTo`, wobei `dateFrom` und `dateTo` jeweils wie ein `date` formatiert sind.
Enumeration	String mit den Werten laut Request-Spezifikation

ID's für erstellte Datensätze

Wenn ein neuer Datensatz erstellt wird und der Status der Antwort ist 201 CREATED, dann enthält diese den HTTP-Header Location, mit der URL des erstellten Datensatzes. An diese URL können folgende Anfragen wie GET|DELETE gesendet werden.

Ergebnislisten (Paging)

Eine spezielle Art von Anfragen stellt das Abrufen von Ergebnislisten dar. Die Ergebnisse werden in Form einer Liste seitenweise zurückgeliefert. Dies hilft die übertragene Datenmenge klein zu halten und bietet der Client-Anwendung eine einfache Möglichkeit zur seitenweisen Anzeige der Suchergebnisse. Ähnliche Techniken werden zum Beispiel von Suchmaschinen im Internet eingesetzt.

Bei Bedarf kann über den Parameter limit definiert werden, wieviel Elemente pro Seite in der Antwort maximal enthalten sein sollen. Standardmäßig werden lediglich 20 Elemente pro Seite zurückgeliefert. Der maximal zulässige Wert für limit ist aber 100.

Mit dem Parameter offset wird definiert, wieviele Datensätze bereits abgefragt wurden. Es sollte immer beim offset 0 begonnen werden, um die ersten Daten in der Antwort zu erhalten. Abhängig von der Antwort muss dann eventuell eine weitere Abfrage mit offset der Anzahl der bereits abgefragten Datensätze erfolgen. Bsp. beim Standardlimit von 20 muss die zweite Abfrage mit offset 20 erfolgen. Der Parameter offset wird also bei Bedarf jeweils um den Wert von limit hochgezählt.

Die Entscheidung, ob weiter abzufragen ist, kann anhand einer der zwei Bedingungen geprüft werden: Wenn weniger Datensätze als limit geliefert werden, dann ist das Ende der Gesamtdatenmenge für diese Kriterien erreicht. Wenn in der Antwort moreData auf false steht, gibt es keine weiteren Daten.

Wenn z. B. 50 Datensätze vorliegen und das limit steht auf 20 (dem Default-Wert), liefern die drei Anfragen mit offset 0, 20 und 40 insgesamt alle Daten.

Fehlermanagement

Eine Anfrage kann aus verschiedenen Gründen vom Gateway als Fehler abgelehnt werden. Dies wird durch den HTTP-Status 4xx/5xx angezeigt.

Die Fehler-Antwort kann ein JSON-Dokument mit Details enthalten. Diese Details sind jeweils auf einen Kontext in der Anfrage bezogen.

Beispiel: POST /access-token ohne alias-Nutzer und Passwort

{
  "_supportToken": "UYM5EcfRzzwpYM9k8LE1cg==",
  "alias": {
    "code": "required",
    "localizedMessage": "Fehlender Parameter."
  },
  "password": {
    "code": "required",
    "localizedMessage": "Fehlender Parameter."
  }
}

Die Antwort enthält ein Feld "_supportToken". Dieses enthält verschlüsselte Informationen zur Anfrage. Für eine optimale Hilfestellung muss der Anwender dieses Token dem Qualitype-Support übermitteln.

Die anderen Objekte sind jeweils ein Kontext mit weiteren Details. Ein Kontext ist meist ein konkretes Feld in der Anfrage. Ist der Kontext "_global", betrifft der Fehler die gesamte Anfrage, kein konkretes Feld. Ist der Kontext "body", so ist der HTTP-body der Anfrage gemeint.

Die Details eines Kontexts enthalten immer genau einen "code", der den Fehler beschreibt. Optional kann eine Liste "arguments" mit relevanten Werten (z.B. Minimal- oder Maximalwerte) mitgegeben werden. Außerdem kann eine Übersetzung für Endanwender als localizedMessage vorhanden sein.

Die Sprache von localizedMessage wird wie folgt bestimmt:

Aus dem Anfrage-Header Accept-Language die Sprache mit der höchsten Priorität, die unterstützt wird (DE/EN),
Die Sprache des Alias-Users, wie in der Weboberfläche eingestellt,
Ansonsten als Standardübersetzung deutsch.

Beispiel: Antwort auf POST /farmers/herd-data mit negativer "herdSize"

"herdSize": {
  "code": "outOfRange",
  "arguments": {
    "min": 0,
    "max": 60000
  }
}

Im Beispiel sind für das Anfrage-Feld/den Kontext "herdSize" ein Wert von -50 übermittelt, es sind aber nur Werte zwischen 0 und 60000 erlaubt. Der Gateway hat leider keine Übersetzung mitgeliefert. Dem Nutzer sollte trotzdem die Information "es ist ein Fehler aufgetreten" angezeigt werden, möglichst mit Referenz auf das Feld. Hat er die Daten über einen Dialog eingegeben, kann er gegebenenfalls dort angezeigt werden. Hat der Nutzer eine Tabelle mit Werten übergeben, kann ggf. auf Spalte/Zeile mit dem fehlerhaften Wert verwiesen werden.

Fachliche Änderungen

Erzeugerbetrieb in Tierhalter umbenannt

Anfragen

Änderungen an Typen

Bitte klicken Sie auf eine der folgenden Typen, um mehr Details zu erfahren.

Änderungen an Anfragen

Bitte klicken Sie auf eine der folgenden Anfragen, um mehr Details zu erfahren.