Notions de base sur les API

Modifié le Lun, 24 Nov. à 12:44 H

Pagination

Tous les points de terminaison GET prennent en charge la pagination et le tri. La pagination est basée sur le curseur et les paramètres sont first (entier) et after (chaîne). Si aucun n'est fourni, l'API renvoie un nombre par défaut de résultats depuis le début en utilisant un tri par défaut. Le nombre de résultats par défaut varie selon l'opération.

Exemple utilisant la pagination

L'en-tête d'autorisation a été supprimé pour simplifier le code et les réponses ont été simplifiées.

GET /années

Renvoie une réponse qui ressemble à ceci :

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

Toutes les réponses ont la même structure afin de faciliter la pagination.

immobilière	Description
totalCount	Le nombre total de ressources
pageInfo.aNextPage	Vrai s'il y a plus de pages
pageInfo.démarrerCurseur	Le curseur de début de la page
pageInfo.finCursor	Le curseur de fin de page
articles	Tableau des éléments renvoyés
item.curseur	Le curseur de l'élément
élément.nœud	La ressource réelle de l'élément

Comme pageInfo.hasNextPage est vrai, nous savons qu'il y a encore des données à collecter. Cette fois-ci, nous utiliserons le paramètre after pour indiquer que nous voulons commencer à une position spécifique.

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

Renvoie une réponse comme celle-ci

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

La variable pageInfo.hasNextPage est fausse, nous n'avons donc plus de données à récupérer.

Réponse d'erreur

Si la requête n'est pas valide, l'API répondra avec le code d'état 400 et une réponse d'erreur. La réponse d'erreur contient une propriété d'erreur qui est un tableau de descriptions d'erreurs.

Propriété	Description
propriété	Nom du bien immobilier concerné par l'erreur
message d'erreur	Le message d'erreur, quel est le problème ?
suggestion	Ce qui devrait être changé

Exemple de réponse d'erreur lors de l'utilisation de 510 comme valeur pour un premier paramètre.

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