Une API REST est une manière de concevoir les échanges entre le client et le serveur de sorte à les uniformaliser, les rendre plus compréhensibles, et faciliter les opérations de tests et de déboguages.
Une requête REST est composée de 3 éléments :
- *une URI* (ou route) qui désigne une ressource ;
- la *méthode HTTP* qui indique le type d'opération à effectuer ;
- le *corps de la requête* contenant des données envoyées au serveur.
Une API REST supporte 5 méthodes HTTP :
- *GET :* lire la ressource.
- POST : ajouter une ressource à une collection.
- *PUT :* modifier entièrement une ressource ou la créer si elle n'existe pas.
- *PATCH :* modifier partiellement une ressource.
- *DELETE :* supprimer une ressource.
L'URI/routes des ressources doivent suivre le même format. On appelle *collection* une ressource qui est elle-même un ensemble de ressources. La modification d'une ressource est effectuée de la sorte :
- `GET /$COLLECTION/` : obtenir la liste des ressources de la collection.
- `POST /$COLLECTION/` : créer une nouvelle ressource dans la collection.
- `GET /$COLLECTION/$ID` : obtenir la ressource d'identifiant `$ID` appartenant à la collection.
- `PUT /$COLLECTION/$ID` : modifier ou créer la ressource d'identifiant `$ID` appartenant à la collection.
- `PATCH /$COLLECTION/$ID` : modifier la ressource d'identifiant `$ID` appartenant à la collection.
- `DELETE /$COLLECTION/$ID` : supprimer la ressource d'identifiant `$ID` appartenant à la collection.
Le corps de la requête et de la réponse REST sont usuellement au format JSON, mais peuvent utiliser n'importe quel format (potentiellement déterminé par la requête REST) :
- URLSearchParams ;
- texte brut ;
- données binaires ;
- XML ;
- etc.
Les API REST sont *sans état*, c'est à dire que le serveur n'enrigistre pas l'état de la connexion/session HTTP. L'état est stocké côté client et les données nécessaires sont inclues dans la requête REST.
Le fait de ne pas stocker d'état côté serveur permet d'éviter certaines attaques DoS de clients malicieux qui ouvriraient des connexions/sessions HTTP afin de surcharger le serveur. Cela permet aussi de mettre en cache la réponse à certaines requêtes REST, ainsi que de plus facilement répartir l'APIREST sur plusieurs serveur en limitant les problématiques de synchronisations.
Pour les opérations de tests et de débogues, le fait qu'il n'y a pas d'état stocké signifie qu'une même requête REST produira le même effet, quel que soit l'état de la connexion/session. Cela permet aussi de mieux comprendre les échanges entre le client et le serveur.
## Websocket
@ -142,8 +204,6 @@ BDD API/FileAPI
## Server Send Event
Contrairement aux WebSockets, les *Server Send Events* ne permettent qu'une communication unidirectionnelle du serveur vers le client. Il est utilisé lorsque le serveur doit régulièrement envoyer des informations au client, sans attendre de réponses, e.g. envoyer des logs en temps réel.
Le principe est très simple, il s'agit d'une requête et d'une réponse HTTP normales, à l'exception que la réponse HTTP est maintenue en vie (`keep-alive`) et est écrite petit à petit (`text/event-stream`). Le corps de la réponse suit le format suivant :
