Anatomie d’une réponse

Qu'est-ce qui revient ?

Vous envoyez une requête, vous recevez une réponse. Vous avez déjà vu le body de la réponse dans les leçons précédentes : c'est du JSON. Mais une réponse ne se limite pas aux données. Regardons ce que le serveur renvoie réellement.

Le status code (est-ce que ça a marché ?)

Chaque réponse est accompagnée d'un status code : un nombre à trois chiffres qui vous dit ce qui s'est passé. Vous en avez probablement déjà vu sans le savoir. Vous avez déjà atterri sur une page "404 Not Found" ? C'est un status code.

Voyons-les en action. Cliquez sur "Send request" sur chacun de ces exemples et observez ce qui se passe :

L'utilisateur #1 existe. Vous devriez obtenir un 200 OK avec les données :

L'utilisateur #9999 n'existe pas. Le serveur ne le trouve pas :

Cet endpoint nécessite une authentification. Vous n'en avez fourni aucune, donc le serveur vous rejette :

Trois URL différentes, trois status codes différents. Mettons des noms dessus.

2xx : succès. Tout s'est bien passé.

• 200 OK : la requête a fonctionné, voici les données demandées. C'est ce que vous avez obtenu pour /users/1.
• 201 Created : la ressource a été créée avec succès (après un POST).
• 204 No Content : la requête a fonctionné, mais il n'y a rien à renvoyer (courant après un DELETE).

4xx : vous avez fait une erreur. Quelque chose ne va pas dans la requête.

• 400 Bad Request : le serveur n'a pas compris votre requête. Peut-être qu'un champ obligatoire est manquant ou que le JSON est mal formaté.
• 401 Unauthorized : vous n'avez pas fourni d'identifiants valides. C'est ce qui s'est passé avec /auth/me. Le serveur ne sait pas qui vous êtes.
• 403 Forbidden : le serveur sait qui vous êtes, mais vous n'avez pas la permission de faire ça.
• 404 Not Found : la ressource demandée n'existe pas. C'est ce qui s'est passé avec /users/9999. Mauvais ID.

5xx : le serveur a planté. La requête est peut-être correcte, mais quelque chose a mal tourné de l'autre côté.

• 500 Internal Server Error : quelque chose a planté sur le serveur. Ce n'est pas votre faute.
• 503 Service Unavailable : le serveur est surchargé ou en maintenance. Réessayez plus tard.

Le premier chiffre vous indique la catégorie : 2 = succès, 4 = erreur côté client, 5 = erreur côté serveur. Rien que ça vous aide à diagnostiquer les problèmes rapidement. Si vous voyez un 4xx, vérifiez votre requête. Si vous voyez un 5xx, c'est côté serveur.

Le body de la réponse (les données)

C'est la partie que vous connaissez déjà bien. Le body, c'est le JSON que le serveur renvoie.

Pour une requête GET réussie, ce sont les données que vous avez demandées. Celle-ci demande seulement 1 utilisateur (limit=1), et uniquement trois champs : firstName, email et age (select=firstName,email,age). Essayez :

Remarquez plusieurs choses dans la réponse. Les données de l'utilisateur sont dans le tableau "users", mais il y a des informations supplémentaires autour : "total" est le nombre total d'utilisateurs dans la base de données, "limit" est le nombre que vous avez demandé, et "skip" est le nombre d'utilisateurs ignorés depuis le début (ici 0, parce que vous partez du début). C'est la pagination : l'API ne vous envoie pas les 208 utilisateurs d'un coup, elle vous donne une tranche. Vous pourriez demander la page suivante avec skip=1. Ce pattern apparaît dans presque toutes les API qui renvoient des listes.

Les réponses d'erreur

Quand quelque chose ne va pas, le serveur renvoie quand même du JSON. Mais au lieu des données que vous vouliez, vous recevez un message d'erreur.

Un 400 Bad Request pourrait ressembler à :

{
  "status": "Error",
  "code": 400,
  "message": "Missing required field: email"
}

Un 401 Unauthorized :

{
  "status": "Error",
  "code": 401,
  "message": "Invalid API key"
}

Un 404 Not Found :

{
  "status": "Error",
  "code": 404,
  "message": "User not found"
}

C'est pour ça que les status codes et les messages d'erreur sont importants dans le travail produit. Quand un utilisateur voit un écran générique "Something went wrong", la réponse API derrière dit souvent exactement ce qui s'est passé. Si vous savez lire cette réponse, vous pouvez fournir à votre équipe technique un rapport de bug bien plus précis que "ça ne marche pas."

Les headers de la réponse

Tout comme les requêtes ont des headers, les réponses en ont aussi. Ils contiennent des métadonnées sur la réponse : sa taille, quand elle a été générée, dans quel format sont les données, etc.

Vous n'aurez pas souvent besoin de lire les headers de réponse en tant que PM, mais deux méritent d'être connus :

• Content-Type: application/json confirme que le body de la réponse est du JSON
• X-RateLimit-Remaining: 47 vous indique combien d'appels API il vous reste avant d'être limité (on parlera du rate limiting dans un chapitre ultérieur)

Votre première requête POST

Jusqu'ici, chaque requête que vous avez envoyée était un GET : "donne-moi ces données." Mais les API ne sont pas en lecture seule. Vous pouvez aussi créer des données en envoyant une requête POST avec un body.

Voici ce qui se passe ci-dessous : vous demandez à DummyJSON de créer un nouvel utilisateur. Le body (le bloc orange) contient les données que vous envoyez : un prénom, un nom, un email et un âge. Cliquez sur "Send request" pour voir ce qui revient.

Vous devriez obtenir un 201 Created. Regardez bien la réponse : vous avez envoyé quatre champs, mais le serveur en a renvoyé cinq. Il a ajouté un id. Vous n'avez pas choisi cet ID. Le serveur l'a généré.

C'est un pattern que vous verrez partout. Quand vous créez un compte sur n'importe quelle application, vous fournissez votre nom et votre email. Le serveur vous attribue un ID utilisateur, une date de création, des paramètres par défaut. Vous envoyez le minimum, la réponse revient enrichie.

Une note importante : DummyJSON est une fausse API pour l'apprentissage. Elle fait semblant de créer l'utilisateur et vous donne une réponse réaliste, mais rien n'est réellement sauvegardé. Si vous envoyez la même requête deux fois, vous obtiendrez le même résultat. Les vraies API (Stripe, Twilio, le backend de votre propre application) stockeraient réellement les données.

Points clés

• Les status codes vous disent si ça a marché (2xx), si vous avez fait une erreur (4xx), ou si le serveur a planté (5xx)
• Le body de la réponse est du JSON, que ce soit des données ou un message d'erreur
• Les réponses d'erreur contiennent souvent un message qui explique exactement ce qui s'est passé
• Une requête envoie le minimum. La réponse revient enrichie avec des ID, des timestamps et des champs calculés.