Einführung Schnittstelle
Allgemeines:
Die Schnittstelle ist in Komponenten und Methoden unterteilt. In der unten aufgeführten Tabelle sind die Links zu den jeweiligen verfügbaren Komponenten und Methoden aufgelistet.
Die Aufrufbeispiele in den Methoden sind im "JSON-Format" aufgebaut und können über "Copy & Paste" und einen gültigen Token getestet werden.
Aufruf:
Die Schnittstelle wird per POST aufgerufen. SOAP (Simple Object Access Protocol) wird derzeit nicht unterstützt.
Die aufzurufende Ziel-URL setzt sich aus "external/#Komponente#/#Methode#" zusammen, z.B.: external/login/getaccessurl
Jede Komponente und Methode stellt per abschließendes "/info" die HTML-Dokumentation zur Verfügung, z.B.: external/login/getaccessurl/info .
Bei einigen Methoden können die Eingabedaten zu Testzwecken validiert werden. Infos hierzu finden Sie in der jeweiligen Methoden-Dokumentation.
Hinter jeder Schnittstelle kann ein JSON-Schema abgerufen werden. Dieses erhalten Sie indem Sie der URL "/request/schema" bzw. "/response/schema" anhängen, z.B. external/login/getlogintoken/request/schema .
Wichtig: Bis auf die Login-Komponente benötigen alle anderen Methoden zur Authentifizierung ein gültiges Token und ein Session-Cookie.
Header:
Wenn der Schnittstelle ein JSON-Objekt geschickt wird, muss folgender Header im POST-Request angegeben sein:
Content-Type: application/json
Content-Encoding: utf8
Body:
Der Body enthält den eigentlichen Request. Im Falle von JSON ist dies der gesamte JSON-String. Im Falle von XML der gesamte XML-String. Alle Daten müssen im UTF8-Format übermittelt werden.
Response:
200 (OK)
Die Anfrage wurde erfolgreich verarbeitet. Die Antwort wurde übertragen.
301 (Moved Permanently)
Die URL ist in dem aufgerufenen Context nicht mehr gültig. Daher wird eine Umleitung (Redirect) durchgeführt.
400 (BadRequest)
Dieser Fehler tritt auf, wenn der Request ein ungültiges JSON beinhaltet
403 (Forbidden)
Dieser Fehler tritt auf, wenn Sie nicht berechtigt sind auf die jeweilige Resource zuzugreifen. Dies kann unterschiedliche Gründe haben:
- nicht Authentifziert / kein Token / kein gültiges Session Cookie
- fehlende Berechtigungen
404 (Not Found)
Dieser Fehler tritt auf, wenn eine Resource / Schnittstelle nicht gefunden wurde. Möglicherweise handelt es sich um einen Schreibfehler in der URL
500 (Internal Server Error)
Dieser Fehler tritt auf, wenn es zu unerwarteten Fehlern bei der Verarbeitung einer Anfrage kommt.
JSON Schema:
Jede Schnittstelle stellt ihr eigenes JSON Schema zur Verfügung. Das JSON Schema kann mittels des Zusatz "GET ../request/schema" oder "GET ../response/schema" abgerufen werden (Beispiel: /external/login/getlogintoken/request/schema). Die URLs stehen in den Dokumentationen zur Verfügung. Details zur Schema Spezifikationen: json-schema.org.
Validierung:
Ebenfalls bieten unsere Schnittstelle die Möglichkeit die Daten gegen das JSON Schema zu validieren. Die Validierung kann für den Request mit dem Zusatz "POST .../validate" ausgeführt werden (Beispiel: POST /external/login/getlogintoken/validate). Die URLs stehen in den Dokumentationen zur Verfügung. Als Rückmeldung erhalten Sie eine Liste von "errors" und "warnings".
Der Response hat folgende Struktur:
- status: string (OK, ERROR)
- success: bool
- errors: string[]
- warnings: string[]
- In den "warnings" geben wir Ihnen Hinweise zu potenziellen Fehlerquellen. Das können z.B. Schreibfehlern bei Properties sein
- In den "errors" werden konkrete Fehler aufgeführt. Darunter fallen z.B. fehlende Pflichtangaben, falsche Datentypen, Enumerationen, Formate
Bitte beachten Sie: Die "errors" und "warnings" können umfangreich werden. Gerade bei wiederholenden Strukturen (object[]), dessen Inhalte z.B. unterschiedliche Pflichtangaben haben, versucht die Validierung die korrekte Struktur zu erkennen. Falls das nicht möglich ist, werden alle möglichen Teilfehler/-warnings ausgegeben.
Beta-Status: Als zusätzlichen "GET"-Parameter können Sie "strict=true" mitschicken. Damit sind auch "additionalProperties" gemäß JSON Schema nicht erlaubt. Dieses Feature kann aktuell zu umfangreichen errors/warnings führen.