HTTP-Status

Die Rest-API arbeitet mit den Status aus RFC 7231. Dieser Status gilt sowohl für die HTTP-Anfrage, als auch für das zurückgegebene Dokument. Die unterschiedlichen Status sind dabei in Statusklassen 1xx Informationen, 2xx Erfolgreiche Operationen, 3xx Umleitungen, 4xx Client-Fehler und 5xx Serverfehler gegliedert.

Aufbau JSON-Dokument

Ein von der Plattform zurückgegebenes JSON-Dokument hat in der Regel folgenden Aufbau:

{
    "dataset": [
        {
            "dataset": {},
            "sys": {
                "code": 200
            }
        },
        {
            "dataset": {},
            "sys": {
                "code": 200
            }
        },
    ],
    "sys": {
        "code": 200,
    }
}

Der Hauptschlüssel dataset beinhaltet die Daten des Dokuments und der Schlüssel sys enthält Metadaten zur Anfrage. Jedes Dokument innerhalb des Hauptschlüssels kann wiederum eine Struktur aus dataset- und sys-Teil enthalten.

Im sys Schlüssel sind auch die Angaben zum Status der Anfrage enthalten. Auf oberster Ebene spiegelt der Eintrag code bzw. error/code den HTTP-Status der Anfrage wieder.

Für eine fehlerfreie Antwort steht der Rückgabewert in sys/code. Optional kann noch eine Textnachricht message und ein Subcode subcode mitgegeben werden. Der Subcode wird bei zur genaueren Analyse des Fehlers herangezogen.

"sys": {
    "message": "201 Created",
    "code": 201
}

Der Gesamtstatus einer Anfrage setzt sich aus den Einzestatus der einzelnen Dokumente zusammen. Werden alle Einzelanfragen mit 200 beantwortet, so ist das Gesamtergebnis ebenfalls 200,

Regeln:

  1. Sind die Status der einzelnen Anfragen identisch, so ist der Gesamtstatus dieser Status
  2. Gibt es in einer Anfrage unterschiedliche Rückgabewerte der selben Statusklasse 1xx, 2xx, 3xx, 4xx oder 5xx, so wird für
    1. 1xx, 2xx, und 3xx jeweils der Gesamtstatus 207 zurückgegeben. Der Standard bezieht sich zwar auf XML-Dokumente, wird aber für diese API auch auf JSON angewendet.
    2. Für die 4xx Klasse wird 400 und
    3. Für die 5xx Klasse wird 500 zurückgegeben.
  3. Werden Status unterschiedlicher Klassen zurückgegeben so wird
    1. Ist eine 5xx Klasse enthalten so ist das Ergebnis 500
    2. Ist eine 4xx Klasse enthalten so ist das Ergebnis 400
    3. Ansonsten wird 200 zurückgegeben.
  4. Ein Leeres Ergebnis ohne definierten Statuscode gibt 200 zurück.

Für JSON-Dokumente sind folgende Rückgabewerte - geordnet nach Statusklassen - erlaubt. Nicht aufgeführte Status werden durch einen Ersatzstatus ersetzt. Bei einem Status 203 würde demzufolge der Ersatzstatus 200 zurückgegeben.

andere Status werden ersetzt durch

Statusklasse Erlaubte Status Ersatzstatus
1xx 400
2xx 200,201,202,204 und 207 200
3xx 304 200
4xx 400, 401, 403, 404 und 409 400
5xx 500, 501, 502 und 502 500

Subcodes

Der Fehlerteil sys/error/ kann zur genaueren Bestimmung des Fehlers einen subcode enthalten.

Subcode Beschreibung
1048 Ein eindeutiger Schlüsselwert ist bereits vorhanden und kann nicht erneut angelegt werden.
1062 Ein für die Operation notwendiger Wert wurde nicht angegeben oder ist null.

Prüfmatrix

Die Prüfmatrix stellt einige Beispiele für die unterschiedlichen Regeln bereit.

Status Status ResultStatus Fehler Regel
404 404 404 ja 1
500 500 500 ja 1
200 200 200 nein 1
200 201 207 nein 2
304 301 207 nein 2
100 101 207 nein 2
400 404 400 ja 2
401 404 400 ja 2
501 500 500 ja 2
501 505 500 ja 2
501 201 500 ja 3
404 201 400 ja 3
404 301 400 ja 3
103 201 200 nein 3