Lire un endpoint
Zoom sur un endpoint
Dans la leçon précédente, vous avez vu la vue d'ensemble : quelles sections existent dans la documentation API et où chercher. Maintenant, zoomons sur une page d'endpoint et apprenons à la lire comme un pro.
Nous allons utiliser DummyJSON, une API gratuite et ouverte qui simule une boutique e-commerce avec des produits, des utilisateurs et des paniers. Pas besoin d'API key. Vous pouvez lire sa documentation sur dummyjson.com/docs/products.
Imaginons que vous construisez une page catalogue produit et que vous devez récupérer une liste de produits depuis l'API. Vous avez ouvert la doc et vous êtes arrivé sur l'endpoint products.
La méthode et l'URL
La première chose sur une page d'endpoint, c'est la méthode et le chemin. Cela vous dit exactement quel verbe HTTP utiliser et où l'envoyer.
Cela se lit : "Envoyez une requête GET vers le chemin /products sur dummyjson.com." GET signifie que vous lisez des données. La base URL est https://dummyjson.com, et chaque endpoint dans leur doc se construit dessus.
Paramètres : obligatoires vs. optionnels
Ensuite vient le tableau de paramètres. C'est là que se trouve l'essentiel de l'information utile. Il vous dit ce que vous pouvez envoyer pour personnaliser la requête.
| Parameter | Type | Required | Description |
|---|---|---|---|
| limit | integer | No | Nombre de résultats à retourner. Par défaut : 30 |
| skip | integer | No | Nombre de résultats à sauter (pour la pagination). Par défaut : 0 |
| select | string | No | Liste de champs à inclure, séparés par des virgules (ex. title,price) |
| sortBy | string | No | Champ de tri (ex. title, price, rating) |
| order | string | No | Sens du tri : 'asc' ou 'desc' |
Quelques points à noter :
Obligatoire vs. optionnel. Tous les paramètres ici sont optionnels. Cela signifie que vous pouvez appeler GET /products sans rien et récupérer les 30 premiers produits. Mais si vous ne voulez que 5 produits triés par prix, vous ajoutez ?limit=5&sortBy=price&order=asc.
Valeurs par défaut. Quand un paramètre indique "Par défaut : 30", cela signifie que si vous ne le précisez pas, l'API utilise 30 automatiquement. Vous n'avez besoin de l'envoyer que si vous voulez une valeur différente.
Type. Vous indique quel type de valeur envoyer. string signifie du texte. integer signifie un nombre entier. Si vous envoyez limit=abc, l'API l'ignorera parce qu'elle attendait un nombre.
Comment les paramètres deviennent une requête
Disons que vous voulez les 5 produits les moins chers, et que seuls le nom et le prix vous intéressent. Voici comment ces paramètres se transforment en une vraie requête :
Chaque paramètre devient une paire clé=valeur dans la query string, reliées par des &. Vous avez vu ça au Chapitre 2 quand nous avons décomposé l'anatomie d'une requête. Maintenant vous pouvez voir comment la doc se traduit directement en ce que vous envoyez.
Le schéma de réponse
Les pages d'endpoint décrivent aussi ce qui revient. C'est le schéma de réponse (response schema) : une liste des champs que l'API retourne et ce qu'ils signifient.
Voici les principaux champs pour chaque produit dans DummyJSON :
| Field | Type | Description |
|---|---|---|
| id | integer | Identifiant unique du produit |
| title | string | Nom du produit |
| description | string | Courte description du produit |
| price | number | Prix en dollars (ex. 9.99) |
| discountPercentage | number | Réduction en cours (ex. 12.96 signifie ~13% de remise) |
| rating | number | Note moyenne (de 0 à 5) |
| stock | integer | Nombre d'articles en stock |
| brand | string | Nom de la marque |
| category | string | Catégorie du produit (ex. smartphones, groceries) |
| thumbnail | string | URL d'une image du produit |
Cela vous dit exactement quels champs attendre dans la réponse JSON. Si votre équipe a besoin du prix et de la disponibilité, vous savez que ces champs sont price (en dollars) et stock (un nombre).
La réponse inclut aussi des métadonnées de pagination au niveau racine :
{
"products": [ ... ],
"total": 194,
"skip": 0,
"limit": 30
}
Les produits sont contenus dans un tableau products. total vous dit combien de produits existent au total. skip et limit vous indiquent quelle tranche vous consultez. Si vous voulez la page suivante, vous enverriez ?skip=30&limit=30.
Status codes
Une bonne doc liste aussi les status codes que l'endpoint peut retourner et ce qu'ils signifient :
| Status code | Meaning |
|---|---|
| 200 OK | La requête a réussi. Les résultats sont dans le corps de la réponse. |
| 400 Bad Request | Paramètre invalide (ex. limit=abc au lieu d'un nombre). |
| 404 Not Found | L'endpoint ou le produit n'existe pas (vérifiez l'URL). |
| 429 Too Many Requests | Vous avez atteint la limite de requêtes. Attendez et réessayez. |
C'est une référence rapide. Si vous recevez un 429, vous savez que ce n'est pas un bug. Vous envoyez simplement trop de requêtes et devez ralentir. Si vous recevez un 400, vérifiez vos paramètres.
Testons pour de vrai
Essayons la requête que nous avons construite plus tôt : les 5 produits les moins chers, en affichant uniquement le titre et le prix.
Vous devriez voir 5 produits triés du moins cher au plus cher. Chacun n'a que id, title et price parce que nous avons utilisé le paramètre select pour filtrer les champs. C'est le cycle : lire la doc, comprendre les paramètres, construire la requête, vérifier la réponse.
Maintenant essayons sans select pour voir l'objet produit complet :
Tous les champs du schéma de réponse sont là : title, price, rating, stock, brand, category, et d'autres encore. La doc vous avait dit à quoi vous attendre, et la réponse correspond.
Il y a aussi un endpoint de recherche
DummyJSON a un endpoint de recherche dédié à /products/search. Il prend un paramètre q (la requête de recherche). Cherchons "phone" :
Même structure de réponse, mêmes champs, mais filtrés sur les produits correspondant à votre recherche. Une fois que vous savez lire un endpoint, les autres suivent le même schéma.
Points clés
- Chaque page d'endpoint montre la méthode, l'URL, les paramètres, le schéma de réponse et les status codes
- Les paramètres marqués "required" doivent être inclus. Les optionnels ont des valeurs par défaut.
- Le schéma de réponse vous dit exactement quels champs attendre dans le JSON
- Lire une page d'endpoint, c'est : méthode + URL, puis paramètres, puis ce qui revient
- Une fois que vous savez lire une page d'endpoint, vous pouvez les lire toutes