Die Schnittstelle 92 enthält die folgenden Services, die die SOAP-Schnittstelle 12 ergänzen:
Diese Services basieren auf REST/JSON und können daher u.a. auf einfache Weise von JavaScript-Clients verwendet werden (z.B. auch von reinen Web-Oberflächen).
Die oben angeführten Schnittstellenspezifikationen entsprechen dem OpenAPI-Standard und wurden mit Tools aus der Swagger-Suite erstellt. In der von Swagger bereitgestellten HTML-Ansicht sind per Default weite Teile der Dokumentation eingeklappt und müssen per Mausklick aufgeklappt werden (siehe Hinweise zur Dokumentation).
Sofern in der jeweiligen Service-Beschreibung nicht explizit anders angeführt, gelten die folgenden Beschreibungen.
Die Version des jeweiligen Service wird einerseits im "version"-Attribut der OpenAPI-Spezifikation festgehalten und andererseits in der angesprochenen URL eingebettet.
Abwärtskompatible Ãnderungen an der Service-Schnittstelle (wie z.B. die Erweiterung um neue Ressourcen) führen nicht zu einer Erhöhung der Schnittstellenversion. Alle anderen Ãnderungen werden ausschlieÃlich im Rahmen einer e-card-Release (2x jährlich) eingebracht und führen zu einer Erhöhung der Schnittstellenversion um 1. Nach einer solchen Erhöhung wird die somit nicht mehr aktuelle Version jedenfalls eine Release lang weiter zur Verfügung gestellt und spätestens mit der nächsten Schnittstellenhebung eingestellt. Es werden daher maximal zwei Versionen parallel angeboten.
Ãnderungen an der Schnittstelle werden im Changelog des Services festgehalten.
Content-Type: application/json
Die Verwendung der Services bedarf keiner vorherigen Authentifizierung.
Fehler werden über ein entsprechendes JSON-Objekt zurückgemeldet, das einen eindeutigen, für automatisierte Verarbeitung geeigneten Fehlercode enthält. Da auf diese Weise bereits entsprechende Granularität gewährleistet wird, wird zwecks Vereinfachung in Fehlerfällen stets der HTTP-Statuscode 500 retourniert (unabhängig davon, wo die Fehlerquelle tatsächlich liegt). Bei allgemeinen Fehlern während der Request-Verarbeitung (wie z.B. bei Requests an nicht bekannte Ressourcen) kann ggf. ein spezifischerer HTTP-Statuscode retourniert werden, was jedoch nicht garantiert wird.
Da jederzeit (auch ohne Schnittstellenhebung) neue Fehlercodes hinzukommen können, sollte der Aufrufer ein entsprechendes "Catch-All" für nicht explizit behandelte Fehlercodes implementieren.
Zusätzlich zum Fehlercode werden auch ein Detail-Fehlercode sowie ein Fehlertext retourniert, die dem Benutzer angezeigt werden sollten. Diese Anzeige ist in jenen Fällen nicht notwendig, in denen die Software automatisiert auf Fehlersituationen reagieren kann. Der Detail-Fehlercode ist zwar meist ident zum Fehlercode, wird aber der Einfachheit halber trotzdem stets retourniert. Die Detail-Fehlercodes werden in den Beschreibungen nicht aufgelistet, da sie für automatisierte Verarbeitung nicht erforderlich sind.
Zusammenfassend:
Es existieren die folgenden Service-unspezifischen Fehlersituationen:
| Code | Text |
|---|---|
| CL-00174 | Es ist ein unerwarteter Fehler aufgetreten. |
| ZS-00184 | Es ist ein Problem bei der Bearbeitung der Anfrage aufgetreten. Hinweis: Diese Meldung wird als Catch-All für strukturelle Probleme im Request verwendet. |
Die Namen von Input-Parametern sind case-sensitiv, es ist bei der Erstellung der Requests also auf korrekte GroÃ-/Kleinschreibung zu achten.
Sofern nicht explizit anders erwähnt, sind in Responses Null-Werte gleichwertig zu nicht vorhandenen Werten zu behandeln. Um die Responses klein zu halten, wird anstelle der Angabe von Null-Werten bevorzugt (jedoch nicht garantiert) das jeweilige Attribut weggelassen.
Um in der Swagger-HTML-Ansicht eines Service die Beschreibung des Requests zur (fiktiven) Ressource "/xyz" angezeigt zu bekommen, sind folgende Mausklicks notwendig:
Analoge Schritte sind zum Ausklappen der Response-Beschreibung notwendig.