Rest API Definition
Bietet die Möglichkeit öffentliche und nicht öffentliche REST API's zur Verfügung zu stellen.
Die effektive URL wird im Endpunkt anhand der aktuellen zugriffs-URL (hier im Beispiel http://localhost:8080/_pro) visualisiert.
Es kann optional eine Basis-URI für alle Endpunkte definiert werden,
Jedem Endpunkt kann optional eine URI definiert werden.
Es stehen alle REST Methoden (GET, POST, PUT, DELETE, HEAD, OPTIONS) zur Verfügung.
Über Anonymer Zugriff besteht die Möglichkeit den Endpunkt ohne vorigen Login zu erreichen. Es ist zu beachten, dass hierbei keine Rechte für Suchabfragen etc. bestehen und bei fehlerhafter Konfiguration (z.B. eine Suche als Super-User) Sensible Daten ohne Zugriffskontrolle ausgelesen werden können. Für einen autorisierten Zugriff siehe Kapitel Authorisierter Zugriff.
Die Antwort erfolgt über die Variable "response", weiterhin stehen folgenden Variablen zur verfügung:
|
Name |
Typ |
Beschreibung |
Richtung |
|
requestHeaders |
Map<String,String> |
Alle Anfrage Header als Map |
Eingehend |
|
queryParameters |
Map<String,String> |
Alle Anfrage Parameter als Map |
Eingehend |
|
response |
Object |
Das Antwort Objekt |
Ausgehend |
|
responseCode |
int |
Der HTTP Code für die Antwort (Standard: 200) |
Ausgehend |
|
responseHeaders |
Map<String,String> |
Benutzerspezifische Antwort Header |
Ausgehend |
|
disableContentHandling |
boolean |
Wenn der Wert "true" ist, wird die Sonderbehandlung des Inhalts-Objektes (zum liefern von z.B. Binärdateien) deaktiviert und das Objekt wird wie jedes andere Objekt serialisiert (z.B. als JSON |
Ausgehend |
|
forceDownload |
boolean |
Gilt nur wenn disableContentHandling auf "false" ist und die Response ein Inhalts-Objekt ist. Ist forceDownload="false", wird der Content-Disposition auf inline gestellt, bei forceDownload="true" wird dieser auf attachment gestellt |
Ausgehend |
Es stehen folgende HTTP Methoden zu Verfügung:
|
Methode |
Request Body? |
Übliche REST Aktion |
|
GET |
Nein |
Lesen |
|
POST |
Ja |
Erstellen |
|
PUT |
Ja |
Ändern |
|
PATCH |
Ja |
Ändern(Partiell) |
|
HEAD |
Nein |
Prüfe vorhanden |
|
DELETE |
Nein |
Löschen |
URI Parameter
Die URI kann optional variable Anteile haben, z.B. fetch/{id}. Der Wert von "id" kann dann über die Variable "id" ausgelesen werden. Wichtig: Der Wert darf / kann kein unmaskiertes "/" enthalten. Der Wert sollte daher immer Url-Encodet werden.
Es können mehrere solcher URI Parameter definiert werden, jedoch sind diese dann auch Pflicht.
Wenn z.B. ein dynamischer Pfad ausgelesen werden soll, kann dies über folgenden Ausdruck erfolgen: {dynamicPath: .+} Wichtig: dies kann nur am Ende der URI erfolgen
Eingabetypen und Sonderformen
Wird als Eingabetyp "Inhalt (de.lobster.scm.actionevent.actor.content.Content)" gewählt, so wird keine automatische Deserialisierung vorgenommen. Der gesamte Anfrage Payload steht dann über das Inhalts Objekt zur Verfügung. So kann z.B. eine Binäre Datei oder ein Custom XML geparst werden.
Eine Anfrage vom Typ "application/x-www-form-urlencoded" wird als Client-Objekt übergeben.
|
Form Data |
Client-Objekt JSON |
|
fname=John&lname=Doe |
{ |
|
fname=John&lname=Doe&fname=Agent&lname=Smith |
{ |
|
fname[]=John&lname[]=Doe |
{ |
Antworttypen
Wird als Antworttyp "Inhalt (de.lobster.scm.actionevent.actor.content.Content)" gewählt, so wird keine automatische Serialisierung vorgenommen. Der gesamte Antwort Payload wird über das Inhalts Objekt zur Verfügung gestellt. Hierbei kann z.B. eine Dateireferenz mit beliebig großen Daten zur Verfügung gestellt werden. Der Content-Type wird hierbei aus dem Inhalts Objekt gelesen und automatisch gesetzt.
In jedem anderen Fall, entscheidet der Rest-Client über den "Accept" Header das Format der Serialisierung.
Authorisierter Zugriff
Wenn der Zugriff über den Browser stattfindet, indem ein Benutzer angemeldet ist, greift automatisch das Session Cookie des angemeldeten Benutzers.
Ansonsten sollte die Authentifizierung über OAuth2 erfolgen (möglich ab _data 4.6)