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:
- Sind die Status der einzelnen Anfragen identisch, so ist der Gesamtstatus dieser Status
- Gibt es in einer Anfrage unterschiedliche Rückgabewerte der selben Statusklasse 1xx, 2xx, 3xx, 4xx oder 5xx, so wird für
- Werden Status unterschiedlicher Klassen zurückgegeben so wird
- 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 |