Panorama : REST, SOAP, GraphQL et les autres

REST n'est pas la seule façon de construire une API. Voici les principales, avec le même besoin à chaque fois : récupérer le livre n°3 d'une bibliothèque en ligne. 

 REST 
 Des ressources identifiées par des URL, manipulées avec les verbes HTTP. Le format est libre, JSON dans la grande majorité des cas. 
 GET /v1/livres/3 HTTP/1.1
Accept: application/json 
 {"id": 3, "titre": "Le Petit Prince", "auteur": "Antoine de Saint-Exupéry"} 
 Simple, lisible, compatible avec tout ce qui parle HTTP. C'est le sujet de ce cours. 

 SOAP 
 Un appel de fonction à distance, emballé dans une enveloppe XML, toujours en POST . Le contrat est décrit dans un fichier WSDL. 
 <soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
 <soap:Body>
 <GetLivre>
 <Id>3</Id>
 </GetLivre>
 </soap:Body>
</soap:Envelope> 
 Encore très présent dans les banques, les assurances et les administrations. 
 Si un jour on vous confie une API SOAP, ne paniquez pas : c'est verbeux, mais c'est bien documenté par nature. 

 GraphQL 
 Une seule URL, et le client décrit exactement les champs qu'il veut. Créé par Facebook en 2015. 
 query {
 livre(id: 3) {
 titre
 auteur
 }
} 
 Pratique quand les besoins du front varient beaucoup. Plus complexe à mettre en cache et à sécuriser. 

 gRPC 
 Appels de fonctions à distance très performants, en binaire (Protocol Buffers) sur HTTP/2. Créé par Google. 
 service Bibliotheque {
 rpc GetLivre (LivreRequest) returns (Livre);
} 
 Surtout utilisé entre microservices, rarement exposé au navigateur. 

 WebSocket 
 Une connexion qui reste ouverte dans les deux sens. Le serveur peut envoyer des messages quand il veut : chat, jeux, cours de bourse, notifications en direct. 

 Webhooks 
 L'inverse d'une API classique : « ne nous appelez pas, on vous appellera ». Vous donnez une URL au service, et c'est lui qui vous envoie une requête HTTP quand un événement se produit (paiement reçu, commit poussé…). 

 Comparatif 
 
 Format Transport Cas d'usage typique 
 
 REST JSON (souvent) HTTP API publiques, back de SPA et d'apps mobiles 
 SOAP XML HTTP (POST) Systèmes d'entreprise historiques 
 GraphQL JSON HTTP (une seule URL) Fronts complexes, données très liées 
 gRPC Binaire (Protobuf) HTTP/2 Communication entre microservices 
 WebSocket Libre Connexion persistante Temps réel 
 Webhooks JSON (souvent) HTTP, dans l'autre sens Notification d'événements