Une API REST

Cours · Spring Boot : écrire le serveur (école d'ingénieur), chapitre 3 · école d'ingénieur, informatique · le début du chapitre, la suite sur Adloun

Notre serveur sait lister les livres. L'application Vue lui demande davantage : les livres d'un rayon, ceux dont le titre contient un mot, la fiche d'un livre précis. Et la Librairie elle-même a besoin d'ajouter des livres à son catalogue, de corriger une fiche, d'en retirer une. Chacune de ces opérations est une requête HTTP ; encore faut-il choisir, pour chacune, l'adresse, la méthode et le code de réponse qui conviennent, de façon que n'importe quel client comprenne l'API sans documentation détaillée.

Ce chapitre présente les conventions des API dites REST et leur écriture avec Spring MVC : lire des paramètres dans l'adresse, recevoir un corps JSON, répondre avec le bon statut et les bons en-têtes. Il montre aussi tout ce que Spring répond de lui-même aux requêtes mal formées. À la fin, la Librairie offre l'API complète du serveur d'essai pour ses livres, et sait en plus les créer, les modifier et les supprimer.

Objectifs du chapitre

Concevoir les adresses d'une API autour de ses ressources.
Choisir la méthode HTTP et le code de statut de chaque opération ; connaître les méthodes sûres et idempotentes.
Lire les paramètres d'une requête (@RequestParam, @PathVariable) et son corps (@RequestBody).
Construire une réponse complète avec ResponseEntity : statut, en-têtes, corps.
Savoir ce que Spring répond seul : 400, 405, 415.

La Librairie du chapitre est dans code/ch3/librairie ; elle écoute toujours le port 8000. Les réponses montrées ont été obtenues avec curl sur l'application en marche.

3.1 Ressources, méthodes, statuts

Une API REST s'organise autour de ressources : les choses que l'on manipule, désignées par des noms. Pour la Librairie :

/api/livres désigne la collection des livres ;
/api/livres/9782956300052 désigne un livre, son ISBN servant d'identifiant.

Les actions ne sont pas dans l'adresse : elles sont exprimées par la méthode HTTP.

Méthode	Sens	Sûre	Idempotente
`GET`	lire	oui	oui
`POST`	créer dans une collection	non	non
`PUT`	remplacer entièrement	non	oui
`PATCH`	modifier en partie	non	non
`DELETE`	supprimer	non	oui

Définition 3.1Méthode sûre, méthode idempotente

Une méthode est sûre si elle ne modifie rien sur le serveur : un navigateur, un robot d'indexation, un cache peuvent l'envoyer sans crainte. Elle est idempotente si l'envoyer deux fois a le même effet que l'envoyer une fois : supprimer deux fois le même livre le laisse supprimé, remplacer deux fois une fiche par le même contenu donne la même fiche. Un client peut donc répéter une requête idempotente dont il n'a pas reçu la réponse (coupure réseau), mais pas un POST : il risquerait de créer deux fois la même chose.

La réponse dit ce qui s'est passé par son code de statut. Le premier chiffre donne la famille : 2 pour un succès, 4 pour une erreur du client, 5 pour une erreur du serveur. Ceux que la Librairie utilisera :

Statut	Signification
200 OK	succès, la réponse contient le résultat
201 Created	ressource créée ; l'en-tête `Location` donne son adresse
204 No Content	succès, sans corps (après une suppression)
400 Bad Request	requête incorrecte (corps illisible, données invalides)
404 Not Found	ressource inexistante
405 Method Not Allowed	méthode non prévue pour cette adresse
409 Conflict	contraire à l'état actuel (ISBN déjà pris)
415 Unsupported Media Type	corps dans un format non accepté
500 Internal Server Error	erreur du serveur lui-même

La suite du cours est sur Adloun

Le chapitre en entier, formules et figures comprises, avec le tuteur, les fiches, les QCM et les exercices.

Lire la suite du cours

En accès libre, sans inscription.

Exercices corrigés de ce chapitre

Lire la suite du cours →