API-Grundlagen

Geändert am Mo, 9 Jun um 3:49 NACHMITTAGS

Paginierung

Alle GET-Endpunkte unterstützen Paginierung und Sortierung. Die Paginierung ist cursorbasiert und die Parameter sind first (Integer) und after (String). Wenn keine angegeben werden, gibt die API eine Standardanzahl von Ergebnissen von Anfang an zurück und verwendet eine Standardsortierung. Der Standardwert für die Anzahl der Ergebnisse variiert je nach Vorgang.

Ein Beispiel für die Verwendung der Paginierung

Der Autorisierungskopf wurde der Einfachheit halber entfernt und die Antworten wurden vereinfacht.

GET /Jahre

Gibt eine Antwort zurück, die in etwa so aussieht:

{
    "totalCount": 4,
    "pageInfo": {
        "hasNextPage": true,
        "startCursor": "aWR4OzA=",
        "endCursor": "aWR4OzE="
    },
    "items": [
        {
            "cursor": "aWR4OzA=",
            "node": {
                "name": "2017"
            }
        },
        {
            "cursor": "aWR4OzE=",
            "node": {
                "name": "2018"
            }
        }
    ]
}

Alle Antworten haben die gleiche Struktur, um die Paginierung zu erleichtern.

Eigentum	Beschreibung
totalCount	Die Gesamtzahl der Ressourcen
pageInfo.hasNextPage	Wahr, wenn es mehr Seiten gibt
pageInfo.startCursor	Der Anfangscursor der Seite
pageInfo.endCursor	Der Endzeiger der Seite
Artikel	Array der zurückgegebenen Elemente
Artikel.Cursor	Der Cursor des Artikels
item.node	Die eigentliche Ressource des Artikels

Da pageInfo.hasNextPage wahr ist, wissen wir, dass es noch mehr Daten zu sammeln gibt. Diesmal verwenden wir den After-Parameter, um anzugeben, dass wir an einer bestimmten Stelle beginnen wollen.

GET /years?first=2&after=aWR4OzE=

Gibt eine Antwort wie diese zurück

{
"totalCount": 4,
"pageInfo": {
"hasNextPage": false,
"startCursor": "aWR4OzI=",
"endCursor": "aWR4OzM="
},
"items": [
{
"cursor": "aWR4OzI=",
"node": {
"name": "2019"
}
},
{
"cursor": "aWR4OzM=",
"node": {
"name": "2020"
}
}
]
}

Die pageInfo.hasNextPage ist false, so dass wir keine weiteren Daten mehr erhalten können.

Fehlerreaktion

Wenn die Anfrage ungültig ist, antwortet die API mit dem Statuscode 400 und einer Fehlerantwort. Die Fehlerantwort enthält eine Fehlereigenschaft, die ein Array von Fehlerbeschreibungen ist.

Objekt	Beschreibung
objekt	Name der Eigenschaft, auf die sich der Fehler bezieht
errorMessage	Die Fehlermeldung, was ist falsch
Anregung	Was sollte geändert werden?

Beispiel für eine Fehlerantwort bei Verwendung von 510 als Wert für einen ersten Parameter.

{
    "Fehler": [
        {
            "property": "first",
            "errorMessage": "510 ungültiger Wert",
            "suggestion": "Muss zwischen 1 und 100 liegen"
        }
    ]
}