Zum Hauptinhalt springen

Unified Request Layout

Im folgenden werden die globalen Konfigurationsparameter eines jeden Requests erklärt. Diese sind unabhängig von den einzelnen jeweils aufgerufenen Methoden und konfigurieren das generelle Verhalten der API pro Request.

Folgende globalen Parameter existieren:

Beschreibung der einzelnen Funktionsparameter​

functions​

Ein Wert vom Typ string als CSV (comma separated value). Mit diesem String wird definiert welche Funktion(en) an der API ausgeführt werden soll(en). Für jede Funktion die übergeben wird, muss auch ein Set an Aufrufparametern angegeben werden.

tipp

Beispiel: Login,GetTags

v​

Version

Repräsentiert das API-Level as Ganzzahl. Änderungen an den Return-Formaten werden bei Updates immer für neuere API Level zur Verfügung gestellt, damit alte Clients weiter funktional bleiben können. Daher ist es nötig bei der Implementierung neuer Funktionen das API Level für calls u.U. anzupassen.

tipp

Beispiel: 17

apiKey​

Für jeden Aufruf an der API muss ein gültiger API Key mitgesendet werden. Über diesen wird die aufrufende Applikation identifiziert.

API Keys können z.b. auf Caller-IPs oder Domains restriktiert werden.

Um einen API Key auf eine Domain zu restriktieren, muss ein gültiger reverse DNS Eintrag am Nameserver konfiguriert sein.

tipp

Beispiel: mySuperNotSecretApiKey

strict​

Definiert ob die API im strikten Modus läuft. Erlaubt sind die Werte true und false

Im strikten Modus ist die Antwort auf jede angefragte Methode in ein Array verpackt. Im nicht-strikten Modus wird das Array ausgelassen, wenn nur eine einzelne Antwort enthalten ist. Dies spart Payload, stellt aber höhere Anforderungen an den Client, da das Antwort-Format von der Anfrage abhängt.

tipp

Standard: false

warnings​

Definiert ob die API Warnings im Response-JSON einbetten soll. Erlaubt sind die Werte true und false.

Diese Einstellung wird nur für die Entwicklung empfohlen, da Kommentare üblichweise in JSON nicht zulässig sind und viele Standard Implementierungen Parser-Fehler erzeugen werden.

tipp

Standard: false

lenient​

Definiert ob die API im lenient, also durchlässigen Modus arbeitet. Erlaubt sind die Werte true und false. Ist Lenient aktiviert, gibt die API für alle gleichzeitig angefragten Methoden eine Antwort, auch wenn z.B. die erste Methode direkt einen Fehler produziert.

info

Dieser Modus ist hilfreich, wenn Teilergebnisse bei der Anfrage optional sind.

tipp

Standard: false

nocache​

API Methoden haben einen Standard Cache von 60s für ein (request, response) Tupel um die Load auf der API bei häufigen, redundaten Anfragen zu verbessern. Einzelne API Methoden haben ggf. ein längeres, oder gar kein Cache Timeout (siehe RPC Dokumentation der einzelnen API Methode).

Das Caching kann durch den Paramter nocache extern ausgeschaltet werden. Clients sollten ein Berechtigtes Interesse haben, den cache bypass zu aktivieren.

info

Dieser Modus ist hilfreich beim Debugging von API Requests.

tipp

Standard: false

readonly​

Schreibende Aufrufe an die API werden vom System automatisch beim ersten Login eines Clients mit Schreibberechtigungen bis zum Logout des selbigen für andere Clients gesperrt. Alle Requests an die API für diesen Guide werden abgelehnt. Um dennoch Daten auslesen zu können (z.B. den Status des Locks), kann der Paramter readonly an die API mitgesendet werden. Damit verzichtet der Client auf seine Schreibrechte und bekommt ein normales, Read-Only Lock von der API zugeteilt. Bis zum Logout oder Aquirement des Write-Locks kann der Client keine Daten an der API schreiben.

forceNamed​

Einzelne API Methoden definieren ihre Parameter In-Order oder über den Parameter-Namen. Erlaubt sind die Werte true und false.

Ist forcedNamed aktiviert, wird die API-seitige Einstellung überschrieben und immer über den Parameter-Namen gemappt. In neuen Clients sollte diese Option immer aktiviert sein.

info

In einer frühen Version dieser API mussten Parameter eines API-Calls immer in der gleichen Reihenfolge angegeben werden, wie Sie im executor definiert sind. Dafür war die bezeichnung der Parameter beliebig. Dieser Zustand ist aus Rückwärtskompatibilitätsgründen immer noch die Standard einstellung, es wird aber empfohlen diese Einstellung durch das Feld forceNamed zu ändern, da ein Mapping über den Parameternamen Fehler vermeidet. Einige JSON Serializer implementierungen sortieren die Keys in JOSN Objekten beim erstellen automatisch um, sodass es bei einem Aufruf ohne forceNamed: true zu falschen Parameter-Mappings kommt.

tipp

Standard: false

userToken​

Hat man z.B. über die Methode Login bereits ein gültiges UserToken erhalten, kann dieses an später aufgerufene Methoden wieder übergeben werden.

Hierdurch spart man sich eine neue Authentifizierung, bis das Usertoken abläuft.

info

Diese Einstellung ist besonders praktisch für Clients ohne Cookie-Unterstützung. Sind Cookies am Client aktiv (z.B. in üblichen Browsern) wird hier ein Token automatisch gesetzt und wiederverwendet.

i18n​

Hier wird die angeforderte Sprache konfiguriert.

Es können entweder eine Sprache z.B. de_DE oder auch mehrere Sprachen mit z.B. de_DE,en_UK angefragt werden.

info

Manche API-Methoden unterstützen keine Rückgaben in mehr als einer Sprache. Bei der Verwendung mit mehreren Sprachen wird eine Exception zurückgegeben.