1. Présentation des réponses HTTP

Pour rappel, d’un point de vue purement technique, le rôle d’une API Rest consiste simplement à :

  • Intercepter une requête HTTP.
  • Puis retourner une réponse HTTP, contenant les informations demandées par le client, au format JSON.

Cependant, est-ce que nous sommes sûr de bien renvoyer une requête HTTP valide ? Car pour le moment, nous renvoyons simplement une chaîne de caractères avec la méthode res.send. Pas sûr que ce soit suffisant…

Nous devons renvoyer une réponse au format JSON, pas une simple chaîne de caractères.

Nous devons donc remédier à ce problème. Passons en revue les différents éléments qu’il nous faut pour retourner une réponse HTTP digne de ce nom :

  • Les données : Cela peut être les données demandées par le client, comme les données d’un pokémon en particulier. Ou alors, des messages d’informations, qui indiquent une erreur ou alors une confirmation comme quoi un pokémon a bien été ajouté au pokédex par exemple. Pour le moment, nous renvoyons des données assez partielles, sous le format d’une chaîne de caractères.
  • Le format JSON : Alors là, on a tout faux. Nos données doivent être au format JSON, pas des chaînes de caractères !
  • Le type MIME : Comme nous l’avons déjà vu, il est nécessaire d’indiquer un type MIME lorsqu’on utilise le protocole HTTP. Nous devons donc ajouter une information supplémentaire pour notre réponse JSON, indiquant que nous renvoyons du JSON. Nous devrons donc ajouter le type MIME sous forme d’une en-tête à notre requête, comme ceci : Content-Type: application/json. Et pour information, lorsque vous demandez une page web HTML à votre navigateur, le type MIME est généralement  Content-Type: text/html; charset=utf-8. C’est toujours bon à savoir. 😉
  • Le code de statut HTTP : Il s’agit d’un code à 3 chiffres, indiquant le statut de la réponse. Ce code n’est pas présent dans la requête HTTP, mais uniquement dans la réponse. Nous verrons plus tard le rôle exact de ce code, mais sachez qu’il est très important de le prendre en compte pour construire une API Rest de qualité. Par exemple, le code 200 indique que la requête a bien été traitée correctement. Lorsque vous naviguez sur Internet, vous êtes déjà surement tombé sur une page vous indiquant qu’une erreur 404 a eu lieu, car la ressource n’a pas été trouvée. C’est le fameux code 404. Donc dans notre API Rest, si un client demande un pokémon qui n’existe pas, avec l’identifiant 9999 par exemple, il faudra lui retourner une réponse avec le code 404, pour lui indiquer que la ressource qu’il demande est introuvable. Voilà, cela devrai être plus clair maintenant !

Une requête et réponse HTTP sont deux éléments légèrement différents. D’ailleurs, Express fait bien la distinction entre les paramètres req et res dans ces points de terminaisons.

Pour la suite, nous allons donc nous concentrer sur la qualité des réponses renvoyées par notre API Rest de pokémons. Cependant, il est encore un peut tôt pour mettre en place les codes de statut HTTP, et la gestion des erreurs associé à ces différents codes.

Mais il y a déjà de quoi faire, car nous devons formater nos réponses en JSON, et améliorer la structure globale de nos réponses, pour que notre API Rest soit le plus simple possible à utiliser. En avant !