Grundlagen zur API

Geändert am Mo, 7 Jul um 5:15 NACHMITTAGS

Paginierung

Alle GET-Endpunkte unterstützen Paginierung und Sortierung. Die Paginierung ist Cursor-basiert und die Parameter sind first (Integer) und after (String). Wird nichts angegeben, gibt die API eine voreingestellte Ergebnisanzahl aus, beginnt dabei am Anfang und verwendet eine Standardsortierung. Der Standardwert für die Anzahl der Ergebnisse variiert je nach Vorgang.

Beispiel für die Paginierung:

Der Autorisierungs-Header wurde der Einfachheit halber entfernt und die Antworten wurden vereinfacht.

GET /years

Gibt eine Antwort aus, 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.

Eigenschaft	Beschreibung
totalCount	Die Gesamtzahl der Ressource
pageInfo.hasNextPage	Wahr, wenn es mehrere Seiten gibt
pageInfo.startCursor	Der Anfangscursor der Seite
pageInfo.endCursor	Der Endcursor der Seite
items	Auflistung der ermittelten Elemente
item.cursor	Der Cursor des Elements
item.node	Die tatsächliche Quelle des Elements

Da pageInfo.hasNextPage wahr ist, wissen wir, dass mehrere Daten vorhanden sind. Diesmal verwenden wir den After-Parameter, um anzugeben, dass wir an einer bestimmten Stelle beginnen wollen.

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

Gibt eine solche Antwort aus:

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

Die pageInfo.hasNextPage ist "falsch". Demnach werden wir keine weiteren Daten mehr erhalten.

Fehlerantwort

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

Eigenschaft	Beschreibung
property	Bezeichnung der Eigenschaft, auf die sich der Fehler bezieht
errorMessage	Die Fehlermeldung mit Beschreibung, was falsch ist
suggestion	Information darüber, was geändert werden sollte

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

{
    "errors": [
        {
            "property": "first",
            "errorMessage": "510 invalid value",
            "suggestion": "Must be between 1 and 100"
        }
    ]
}