APIs & Services

REST, GraphQL, gRPC, contrats, versioning, documentation & tests : tout ce que le back-end dev doit maîtriser pour exposer des services propres, stables et observables.

REST, GraphQL, gRPC, events Contrats, versioning, compat ascendante Auth, scopes, rate limiting & tests d’API

Rappels HTTP

Verbes : GET (lecture), POST (création), PUT/PATCH (MAJ), DELETE (suppression).
Statuts : 2xx succès, 4xx erreur client, 5xx erreur serveur.
Idempotence : GET, PUT, DELETE doivent pouvoir être rejoués sans effet secondaire.

GET /orders/123      -> 200 OK
                            POST /orders         -> 201 Created
                            DELETE /orders/123   -> 204 No Content

REST (simplifié)

Ressources adressables par URI : /orders/123.
Représentations (JSON, XML…) + liens éventuellement (HATEOAS light).
Sans état côté serveur (stateless) pour la scalabilité.

GET /orders/123
                            {
                            "id": "123",
                            "status": "paid",
                            "_links": {
                            "cancel": { "href": "/orders/123/cancel" }
                            }
                            }

Exemple minimal FastAPI

from fastapi import FastAPI
                            from pydantic import BaseModel

                            class OrderIn(BaseModel):
                            amount: float

                            app = FastAPI()

                            @app.post("/orders", status_code=201)
                            def create_order(payload: OrderIn):
                            # TODO: persister...
                            return {"id": "ord_123", "amount": payload.amount}

Ressources & naming

Pluriel en snake/kebab : /users, /user-groups.
Relations : /users/{id}/orders.
Actions “verbes” → sub-ressources : POST /orders/{id}/cancel.

GET  /orders?status=paid&page=2
                            POST /orders/{id}/cancel

Filtres, tri, pagination

Filtres via query params : ?status=paid&from=2025-01-01.
Tri : ?sort=-created_at.
Pagination : ?page=2&page_size=50 (ou offset/limit).

GET /orders?page=1&page_size=20
                            {
                            "items": [...],
                            "page": 1,
                            "page_size": 20,
                            "total": 142
                            }

Erreurs & codes

Validation → 400, Auth → 401, droits → 403, non trouvé → 404.
Inclure un code d’erreur applicatif + message.

HTTP/1.1 422 Unprocessable Entity
                            {
                            "error": "INVALID_STATUS",
                            "message": "Status must be one of: draft, paid, cancelled"
                            }

Checklist design REST

Endpoints stables & documentés, pas de “/doStuff” obscur.
Contrats de réponse cohérents (même structure partout).
Pas de payload sur GET, éviter les “RPC HTTP” déguisés.

GraphQL

Client choisit exactement les champs qu’il veut.
Un seul endpoint, schéma typé.
Très pratique pour front-end (mobile, SPA).

type Query {
                            order(id: ID!): Order
                            }

                            type Order {
                            id: ID!
                            status: String!
                            total: Float!
                            }

query {
                            order(id: "123") {
                            id
                            total
                            }
                            }

gRPC

Protobuf + HTTP/2, très efficace inter-services.
Streaming bi-directionnel possible.
Contrats forts; clients générés auto.

syntax = "proto3";

                            service Orders {
                            rpc GetOrder(GetOrderRequest) returns (OrderResponse);
                            }

                            message GetOrderRequest { string id = 1; }
                            message OrderResponse { string id = 1; string status = 2; }

Choisir quoi ?

REST : par défaut, surtout B2B / intégrations publiques.
GraphQL : besoin fort de flexibilité côté front.
gRPC : microservices internes haute perf, streaming.

OpenAPI (Swagger)

Source de vérité du contrat REST.
Génération doc & SDK clients.
Base pour tests automatisés.

paths:
                            /orders/{id}:
                            get:
                            summary: Get order by id
                            parameters:
                            - in: path
                            name: id
                            schema: { type: string }
                            responses:
                            "200": { description: OK }

Versioning

Version dans l’URL : /api/v1/orders.
Compat ascendante : ajouter des champs, ne pas en supprimer.
Deprecation header + doc : annoncer la fin d’un endpoint.

Breaking changes & contrats

Changer un type ou supprimer un champ = breaking.
Utiliser tests de contrat (Pact, etc.).
Prévoir une période de cohabitation v1/v2.

{
                            "field": "status",
                            "breaking_change": "enum reduced",
                            "mitigation": "introduce new field 'lifecycle_status'"
                            }

Auth / Authz

JWT / OAuth2 / API keys selon cas.
Scopes & rôles : orders:read, orders:write.
Rotation des clés & tokens courts + refresh.

Authorization: Bearer <access_token>

Rate limiting & quotas

Limiter par IP, client_id, user_id.
Retourner des infos dans les headers :

HTTP/1.1 429 Too Many Requests
                            X-RateLimit-Limit: 100
                            X-RateLimit-Remaining: 0
                            Retry-After: 60

Sécurité applicative

Validation stricte des entrées (types, tailles, patterns).
Ne pas exposer les stack traces dans les réponses.
Audit log pour les actions sensibles (login, suppression, etc.).

Docs essentielles

Guide “Getting started” en 5–10 minutes.
Exemples d’appels (curl, Python, JS, Postman).
Politique d’auth, quotas, erreurs typiques.

Exemple d’appel curl

curl -X POST https://api.example.com/v1/orders \
                            -H "Authorization: Bearer <token>" \
                            -H "Content-Type: application/json" \
                            -d '{"amount": 123.45}'

Snippet client Python

import requests
                            r = requests.post(
                            "https://api.example.com/v1/orders",
                            headers={"Authorization": f"Bearer {token}"},
                            json={"amount": 123.45},
                            )
                            print(r.status_code, r.json())

DX côté équipe interne

Environnements “sandbox” pour tests.
Postman collections / Insomnia exportées.
Exemples d’erreurs fréquentes et comment les corriger.

Tests unitaires & intégration

Tester la logique métier sans HTTP (services).
Tests d’API avec client HTTP in-process (ex : TestClient FastAPI).

def test_create_order(client):
                            r = client.post("/orders", json={"amount": 10})
                            assert r.status_code == 201

Tests de contrat (consumer-driven)

Producteur & consommateur partagent un contrat.
Si on casse le contrat, la CI échoue.

{
                            "consumer": "frontend-app",
                            "provider": "orders-api",
                            "interaction": {
                            "request": { "method": "GET", "path": "/orders/123" },
                            "response": { "status": 200, "body": { "id": "123" } }
                            }
                            }

Tests de charge & smoke tests

Locust, k6, JMeter… pour simuler le trafic.
Smoke test après déploiement : quelques appels critiques.

# Exemple Locust (Python)
                            class OrdersUser(HttpUser):
                            @task
                            def get_order(self):
                            self.client.get("/orders/123")

Style	Transport / format	Forces	Cas d’usage typiques
REST	HTTP + JSON	Simple, universel, facilement testable.	APIs publiques, B2B, exposer des ressources métier.
GraphQL	HTTP + schéma typé	Le client choisit les champs, peu de sur/under-fetching.	Front web/mobile avec besoins complexes de données.
gRPC	HTTP/2 + Protobuf	Très performant, contrats forts, génération de clients.	Microservices internes, streaming, faible latence.
Events	MQ / log d’événements (Kafka, RabbitMQ…)	Découplage fort, asynchrone, scalabilité.	Intégrations, side-effects, synchronisation de données.

Exemple REST (FastAPI)

@app.get("/orders/{id}")
                            def get_order(id: str):
                            return {"id": id, "status": "paid"}

Exemple gRPC (extrait .proto)

service Orders {
                            rpc GetOrder(GetOrderRequest) returns (OrderResponse);
                            }

                            message GetOrderRequest { string id = 1; }
                            message OrderResponse  { string id = 1; string status = 2; }

Contrat = source de vérité

Spécification OpenAPI, schema GraphQL ou proto gRPC.
Versionné dans Git, validé en CI.
Point de départ pour la doc & les SDK.

paths:
                            /orders/{id}:
                            get:
                            operationId: getOrder
                            responses:
                            "200":
                            description: OK

Versioning

URL versionnée : /api/v1/..., /api/v2/....
Compat ascendante : on peut ajouter des champs, pas en supprimer.
Deprecation header + date d’expiration annoncée.

Deprecation: true
                            Sunset: Wed, 31 Dec 2025 23:59:59 GMT

Breaking / non-breaking

Changer un type (string → int) = breaking.
Rendre un champ obligatoire = breaking.
Ajouter un champ optionnel = OK (non-breaking).

{
                            "change": "field 'status' enum extended",
                            "impact": "non-breaking for tolerant clients"
                            }

Mini-checklist “contrat API”

Contrat versionné, validé par lint / CI ?
Stratégie écrite pour déprécier/remplacer un endpoint ?
Tests de contrat (consumer/provider) en place pour éviter les régressions ?

Auth & scopes

JWT / OAuth2 : access token court, refresh token plus long.
Scopes fonctionnels : orders:read, orders:write.
Rôles & permissions côté service (RBAC / ABAC).

Authorization: Bearer <access_token>

Rate limiting & protections

Limiter par clé API / user / IP.
Réponse claire en cas de 429 :

HTTP/1.1 429 Too Many Requests
                            X-RateLimit-Limit: 100
                            X-RateLimit-Remaining: 0
                            Retry-After: 60

Protection contre brute force, input validation stricte.

Tests d’API à couvrir

Happy path pour chaque endpoint.
Erreurs : auth manquante, droits insuffisants, payload invalide.
Tests de charge sur endpoints critiques (Locust, k6…).

def test_unauthorized(client):
                            r = client.get("/orders/123")
                            assert r.status_code == 401

Anti-patterns fréquents

API “chatty” : 10 appels pour charger une page → penser agrégation / BFF.
Utiliser POST pour tout (même des lectures).
Coupler le modèle d’API 1:1 au modèle de DB interne.
Changer les réponses sans préavis (breaking changes silencieux).
Absence d’auth ou même clé identique pour tous les clients.

Checklist de design d’API (extrait)

[
                            "Endpoints nommés de manière cohérente ?",
                            "Verbes HTTP & statuts respectés ?",
                            "Payloads validés & typés (schemas) ?",
                            "OpenAPI à jour & publié ?",
                            "Auth + scopes définis ?",
                            "Rate limiting & quotas configurés ?",
                            "Logs structurés avec trace-id ?",
                            "Tests d’API dans la CI ?"
                            ]

APIs & Services

1. Fundamentals HTTP & REST

2. Design d’API REST

3. GraphQL & gRPC

4. Contrats, versioning & compatibilité

5. Sécurité & limites

6. Documentation & DX

7. Tests d’API

8. Anti-patterns & checklist finale