Une API (Application Programming Interface) est un contrat qui définit comment deux programmes communiquent entre eux. Elle expose des opérations que d’autres applications peuvent appeler sans connaître l’implémentation interne.
Client API Serveur
│ │ │
│── Requête (contrat) ────► │── logique métier ─────────►│
│◄── Réponse (contrat) ─── │◄── résultat ───────────────│
L’API est une interface, pas une implémentation. Plusieurs technologies peuvent exposer la même API.
Les grandes familles d’API
| Type | Paradigme | Transport | Format | Cas d’usage |
|---|---|---|---|---|
| REST | Ressources + CRUD | HTTP/1.1, HTTP/2 | JSON, XML | APIs web, microservices |
| GraphQL | Requêtes flexibles | HTTP | JSON | Apps mobile, front-end riche |
| gRPC | Appels de fonctions | HTTP/2 | Protobuf (binaire) | Microservices internes, Kubernetes |
| WebSocket | Canal bidirectionnel | TCP (via HTTP upgrade) | JSON, binaire | Temps réel (chat, jeux, trading) |
| Webhook | Callback événementiel | HTTP POST | JSON | Notifications asynchrones |
| SOAP | Messages XML | HTTP, SMTP | XML + WSDL | Legacy enterprise (bancaire, ERP) |
Comparatif : REST vs GraphQL vs gRPC vs WebSocket
| Critère | REST | GraphQL | gRPC | WebSocket |
|---|---|---|---|---|
| Couplage client/serveur | Faible | Faible | Fort (.proto) | Moyen |
| Flexibilité requête | Fixe (endpoints) | Totale (client choisit les champs) | Fixe (méthodes) | Libre |
| Performance | Moyen | Moyen | Très haute | Haute |
| Caching HTTP | ✅ natif | ❌ difficile | ❌ | ❌ |
| Streaming | ❌ (SSE partiel) | ✅ subscriptions | ✅ bidirectionnel | ✅ natif |
| Lisibilité | Haute (JSON) | Haute (JSON) | Basse (binaire) | Variable |
| Tooling | Excellent | Bon | Bon (Go, Java) | Bon |
| Idéal pour | APIs publiques | Frontend riche | Services internes | Temps réel |
Webhook — le pattern événementiel
Un webhook est une API “inversée” : c’est le serveur qui appelle le client quand un événement survient, plutôt que le client qui interroge périodiquement.
Sans webhook (polling) :
Client ──► GET /status (toutes les 5s) [inefficace]
Client ──► GET /status
Client ──► GET /status ← réponse utile enfin
Avec webhook (push) :
Serveur ──► POST https://client.com/webhook [dès l'événement]
{ "event": "payment.success", "amount": 99.99 }
Exemples concrets :
- GitHub → notifie votre CI/CD à chaque push
- Stripe → notifie votre backend à chaque paiement
- Slack → webhook entrant pour poster des messages
API publique vs privée vs partenaire
| Type | Audience | Auth | Exemples |
|---|---|---|---|
| Publique | Tout le monde | API Key ou OAuth | Twitter API, OpenWeatherMap |
| Partenaire | Partenaires commerciaux | OAuth2, certificats | Stripe, Twilio |
| Privée (interne) | Services internes | mTLS, JWT interne | Microservices, Kubernetes |
Notes détaillées
- HTTP — Méthodes, Codes et Headers — référence méthodes (GET/POST/PUT…), codes de statut, headers, CORS
- API REST — principes REST, modélisation ressources, versioning, pagination, OpenAPI
- API GraphQL — schéma SDL, queries, mutations, subscriptions, avantages vs REST
- API WebSocket — canal bidirectionnel persistant, handshake, Socket.IO, SSE
- Authentification API — API Keys, JWT, OAuth2, OpenID Connect, mTLS
- RPC — gRPC : appels distants via Protobuf + HTTP/2
En relation avec
- Requêtes HTTP et HTTPS — structure bas niveau du protocole HTTP (TLS, versions, flux)
- TLS et SSL — sécuriser les APIs avec HTTPS et mTLS
- Protocoles OSI - Index — contexte couche OSI (L7)