Comprendre les API : REST, GraphQL et WebSockets expliqués

Les API — interfaces de programmation d'applications — constituent la structure invisible du web moderne. Chaque fois que vous consultez la météo sur votre smartphone, payez un achat en ligne ou naviguez sur un réseau social, une multitude d'appels API sont effectués en arrière-plan. Maîtriser les différents paradigmes d'API, savoir lequel choisir et comment les sécuriser est une compétence cruciale pour tout développeur.

Dans ce guide, nous explorerons quatre architectures majeures — REST, GraphQL, WebSockets et gRPC — et nous analyserons les méthodes d'authentification, les stratégies de limitation de requêtes et les bonnes pratiques de documentation.

REST : La référence industrielle

REST (Representational State Transfer) est l'architecture dominante depuis plus de quinze ans. Elle considère les ressources serveur comme des URLs et utilise les méthodes standards du protocole HTTP pour interagir avec elles.

• GET — Récupérer une ressource
• POST — Créer une nouvelle ressource
• PUT / PATCH — Mettre à jour une ressource existante
• DELETE — Supprimer une ressource

GET /api/v1/users/42 HTTP/1.1
Host: example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

---
HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 42,
  "name": "Jane Doe",
  "email": "[email protected]",
  "role": "admin"
}

Quand utiliser REST ?

REST est idéal lorsque les ressources correspondent naturellement à des opérations CRUD (Create, Read, Update, Delete) : systèmes de gestion de contenu, catalogues e-commerce, services de comptes utilisateurs. Sa compatibilité étendue avec les outils actuels, de Postman aux générateurs OpenAPI, en fait le choix le plus sécurisant pour les API publiques.

Les limites de REST

Les deux problèmes principaux sont le sur-fetching (récupérer plus de données que nécessaire) et le sous-fetching (avoir besoin de plusieurs appels pour assembler des données liées). Par exemple, afficher un tableau de bord complet pourrait nécessiter trois requêtes distinctes vers /users/42, /users/42/orders et /users/42/notifications.

GraphQL : Requêtez exactement ce dont vous avez besoin

Développé par Facebook et rendu open-source en 2015, GraphQL résout les problèmes de sur-fetching et de sous-fetching en permettant au client de définir précisément la forme des données attendues dans une seule requête.

query DashboardData {
  user(id: 42) {
    name
    email
    orders(last: 5) {
      id
      total
      status
    }
    notifications(unread: true) {
      message
      createdAt
    }
  }
}

Le serveur renvoie un objet JSON correspondant rigoureusement à cette structure, optimisant ainsi la bande passante, ce qui est crucial pour les applications mobiles.

Quand utiliser GraphQL ?

• Applications manipulant des données imbriquées ou complexes (réseaux sociaux, dashboards)
• Équipes gérant plusieurs plateformes clients aux besoins de données différents
• Prototypage rapide où l'interface frontend évolue plus vite que le backend

Les compromis de GraphQL

GraphQL déplace la complexité vers le serveur. Vous devrez gérer la profondeur des requêtes pour éviter des appels coûteux à votre base de données. Le cache HTTP standard devient moins efficace, chaque requête étant généralement une méthode POST sur une endpoint unique. De plus, vous perdez la sémantique native des codes d'état HTTP, puisque les erreurs sont souvent renvoyées dans le corps de réponse 200.

WebSockets : Communication bidirectionnelle en temps réel

Contrairement aux modèles de requête-réponse classiques, les WebSockets établissent une connexion TCP persistante et full-duplex, permettant aux deux parties d'envoyer des messages instantanément à tout moment.

const socket = new WebSocket('wss://chat.example.com/ws');

socket.addEventListener('open', () => {
  socket.send(JSON.stringify({
    type: 'subscribe',
    channel: 'stock-prices'
  }));
});

socket.addEventListener('message', (event) => {
  const data = JSON.parse(event.data);
  console.log(`${data.symbol}: $${data.price}`);
});

Quand utiliser les WebSockets ?

• Applications de messagerie — envoi instantané sans polling
• Dashboards en direct — tickers boursiers, résultats sportifs, capteurs IoT
• Édition collaborative — co-rédaction en temps réel type Google Docs
• Jeux en ligne — synchronisation d'état à faible latence

Points d'attention des WebSockets

Les WebSockets nécessitent une connexion maintenue, ce qui complexifie le passage à l'échelle horizontal. Vous aurez besoin d'un courtier de messages (message broker) comme Redis Pub/Sub ou de services dédiés (Socket.IO, Pusher, Ably) pour diffuser les messages sur plusieurs instances serveur. La gestion des connexions (heartbeats, reconnexions) ajoute une charge de maintenance technique.

gRPC : Communication haute performance

Créé par Google, gRPC utilise HTTP/2 pour le transport et les "Protocol Buffers" (protobuf) pour la sérialisation binaire. Il est optimisé pour les échanges ultra-rapides entre microservices.

syntax = "proto3";

service UserService {
  rpc GetUser (UserRequest) returns (UserResponse);
  rpc ListUsers (ListRequest) returns (stream UserResponse);
}

message UserRequest {
  int32 id = 1;
}

message UserResponse {
  int32 id = 1;
  string name = 2;
  string email = 3;
}

Quand utiliser gRPC ?

• Communication interne entre microservices où la latence est critique
• Environnements polyglottes — gRPC génère des bibliothèques clients dans presque tous les langages
• Workloads de streaming — le streaming bidirectionnel est une fonctionnalité native

gRPC est moins adapté aux clients navigateurs (bien que gRPC-Web existe) et aux API publiques où le JSON lisible par l'humain reste préféré pour le débogage.

Comparatif rapide

Méthodes d'authentification API

La sécurité est un pilier fondamental. Voici les stratégies les plus répandues :

1. Clés d'API

Un jeton simple passé via un header ou un paramètre. Simple à implémenter, mais manque de granularité. Idéal pour du serveur-à-serveur ou des quotas par projet.

GET /api/v1/weather?city=Paris HTTP/1.1
X-API-Key: sk_live_abc123def456

2. OAuth 2.0

Le standard pour l'autorisation déléguée. Un utilisateur permet à votre application d'accéder à ses données sans partager ses identifiants. Le flux "Authorization Code" avec PKCE est vivement recommandé pour les applications mobiles et SPA.

3. JWT (JSON Web Tokens)

Les JWT sont des jetons auto-portés contenant des informations (claims) encodées en Base64 et signées cryptographiquement. Ils permettent une authentification sans état (stateless), le serveur n'ayant pas besoin de consulter une base de session à chaque requête.

// Header
{ "alg": "HS256", "typ": "JWT" }

// Payload
{
  "sub": "42",
  "name": "Jane Doe",
  "role": "admin",
  "iat": 1719350400,
  "exp": 1719354000
}

// Signature
HMACSHA256(base64(header) + "." + base64(payload), secret)

Limitation de débit (Rate Limiting)

Cette mesure protège vos ressources contre les abus. Les stratégies classiques :

1. Fenêtre fixe — N requêtes par période (ex: 100/min). Simple mais peut causer des pics en fin de fenêtre.
2. Fenêtre glissante — Plus fluide, analyse le chevauchement des périodes.
3. Jeton (Token Bucket) — Les jetons se remplissent à taux constant. Autorise des pics tout en limitant la moyenne.
4. Seau percé (Leaky Bucket) — Traitement à débit constant, idéal pour lisser le trafic.

Informez toujours vos utilisateurs via les headers de réponse :

HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 73
X-RateLimit-Reset: 1719354000

Bonnes pratiques de documentation

Une bonne API repose sur une excellente documentation :

• Utilisez OpenAPI / Swagger pour vos API REST pour permettre la génération de clients et le test interactif.
• Proposez des exemples concrets — montrez des paires de requêtes/réponses réelles.
• Documentez les erreurs — listez tous les codes d'erreur avec leurs significations et solutions.
• Gérez le versionnement — soit via l'URL (/v1/) soit via les headers.
• Créez des guides de démarrage rapide — le développeur veut tester l'authentification en 5 minutes chrono.

Pour GraphQL, le schéma sert de documentation native. Des outils comme GraphiQL permettent d'explorer types et requêtes de manière interactive.

Manipuler les données API

Le JSON est le format roi. Lors du développement, il est fréquent d'avoir besoin de formater (beautifier) du JSON illisible ou de le minifier pour le transfert. Par ailleurs, la capacité à encoder ou décoder des chaînes en Base64 est essentielle pour inspecter vos jetons JWT et vos flux d'authentification rapidement sans scripts complexes.

En résumé

Le choix dépend de vos besoins : REST reste la référence pour sa simplicité. GraphQL excelle dans la flexibilité. WebSockets sont indispensables pour le temps réel, et gRPC pour la performance interne. Combinez cela à une sécurité rigoureuse et une documentation claire, et vous obtiendrez des API que les développeurs adopteront avec plaisir.