4.9. REST-API

Allgemeines

Die REST-API dient dem Abruf von Metadaten von Orm-Type, dem Abruf von Auswahllisten und Auswahllistenwerten und dem Abruf und der Aktualisierung einzelner und mehrerer Datensätze.Sie verwendet allgemeingültige Standardvorgehensweisen im REST-Umfeld um auf die Daten zuzugreifen. Die Kommunikation zwischen Server und Client findet über das http-Protokoll statt und verwendet inhaltlich in den meisten Fällen JSON. Die API kann nur auf Datensätze zugreifen, die OrmBABase als Basistypen und überhaupt einen Orm-Typen haben.

Versionierung der API

Die REST-API ist – bis auf die Authentifizierung – versioniert, was sich auch in den URIs zu den einzelnen Endpunkten widerspiegelt: /rest/v1/.... Bei größeren strukturellen Änderungen in der Zukunft ist geplant, die bisherige API mindestens ein Release lang in ihrer Funktion unter der entsprechenden Version unverändert beizubehalten.

OPTIONS-Anfragen

Alle Endpunkte – wiederum bis auf die Authentifizierung – bieten die Möglichkeit einer Anfrage der Methode “OPTIONS”. Diese Anfrage liefert niemals Inhalte zurück (Status: “204 No content”), in den http-Headern der Antwort findet sich aber der Header “Allow”, welcher die http-Methoden aufzählt, mit denen dieser Endpunkt umgehen kann.
Beispiel:

OPTIONS https://<server>/<app>/rest/v1/typeinfo/
Allow: GET,OPTIONS

Cache-Unterstützung und bedingte Anfragen

Die REST-API unterstützt explizit, dass Clients die gelieferten Daten zwischenspeichern. Zu diesem Zweck werden bedingte Anfrage auf Basis der Header Last-Modified und ETag unterstützt.
Eine bedingte Anfrage muss sich dann entweder auf das Datum der letzten Änderung oder auf das zuletzt gelieferte ETag derselben Anfrage beziehen; hierfür werden die Anfrage-Header If-Modified-Since und If-Unmodified-Since für das Änderungsdatum beziehungsweise If-Match und If-None-Match mit dem letzten ETag verwendet.
Trifft die Bedingung zu, so wird die entsprechende Anfrage vollumfänglich verarbeitet und ein entsprechendes Ergebnis zurückgeliefert. Trifft die Bedingung nicht zu, liefert die API lediglich den Status “304 Not modified” ohne Inhalte zurück. Dieses Verhalten dient der Minimierung unnötigen Netzwerkverkehrs, muss aber von Clients nicht zwingend implementiert werden.

Fehlerrückgaben

Sofern irgend möglich wird die REST-API im Fehlerfall eine Liste von Fehlerstrukturen in Verbindung mit einem Passenden Antwortstatus zurückgeben. Diese Fehlerstrukturen beinhalten eine Fehlermeldung in Benutzersprache, einen Stacktrace (wenn möglich) und gegebenenfalls weitere Details.
Beispiel:

{
    "ErrorMessage": "Der Orm-Typ 'OrmCRMUserProfileaa' konnte nicht ermittelt werden.",
    "StackTrace": null,
    "Details": null
}