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