# 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.

```http
GET /v1/livres/3 HTTP/1.1
Accept: application/json
```

```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.

```xml
<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.

<p class="callout info">Si un jour on vous confie une API SOAP, ne paniquez pas : c'est verbeux, mais c'est bien documenté par nature.</p>

### GraphQL

Une seule URL, et le client décrit **exactement** les champs qu'il veut. Créé par Facebook en 2015.

```graphql
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.

```protobuf
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

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