api-design

Modèles de Conception d'API

Conventions et meilleures pratiques pour concevoir des API REST cohérentes et adaptées aux développeurs.

Quand Activer

• Conception de nouveaux points de terminaison d'API
• Révision de contrats d'API existants
• Ajout de pagination, filtrage ou tri
• Implémentation de la gestion des erreurs pour les API
• Planification de la stratégie de versioning d'API
• Création d'API publiques ou destinées aux partenaires

Conception des Ressources

Structure d'URL

# Les ressources sont des noms, au pluriel, en minuscules, en kebab-case
GET    /api/v1/users
GET    /api/v1/users/:id
POST   /api/v1/users
PUT    /api/v1/users/:id
PATCH  /api/v1/users/:id
DELETE /api/v1/users/:id

# Sous-ressources pour les relations
GET    /api/v1/users/:id/orders
POST   /api/v1/users/:id/orders

# Actions qui ne correspondent pas au CRUD (utiliser les verbes avec parcimonie)
POST   /api/v1/orders/:id/cancel
POST   /api/v1/auth/login
POST   /api/v1/auth/refresh

Règles de Nommage

# BON
/api/v1/team-members          # kebab-case pour les ressources multi-mots
/api/v1/orders?status=active  # paramètres de requête pour le filtrage
/api/v1/users/123/orders      # ressources imbriquées pour la propriété

# MAUVAIS
/api/v1/getUsers              # verbe dans l'URL
/api/v1/user                  # singulier (utiliser le pluriel)
/api/v1/team_members          # snake_case dans les URL
/api/v1/users/123/getOrders   # verbe dans la ressource imbriquée

Méthodes HTTP et Codes d'État

Sémantique des Méthodes

Méthode	Idempotente	Sûre	Utilisation
GET	Oui	Oui	Récupérer des ressources
POST	Non	Non	Créer des ressources, déclencher des actions
PUT	Oui	Non	Remplacement complet d'une ressource
PATCH	Non*	Non	Mise à jour partielle d'une ressource
DELETE	Oui	Non	Supprimer une ressource

*PATCH peut être rendu idempotent avec une implémentation appropriée

Référence des Codes d'État

# Succès
200 OK                    — GET, PUT, PATCH (avec corps de réponse)
201 Created               — POST (inclure l'en-tête Location)
204 No Content            — DELETE, PUT (sans corps de réponse)

# Erreurs client
400 Bad Request           — Échec de validation, JSON malformé
401 Unauthorized          — Authentification manquante ou invalide
403 Forbidden             — Authentifié mais non autorisé
404 Not Found             — La ressource n'existe pas
409 Conflict              — Entrée en double, conflit d'état
422 Unprocessable Entity  — Sémantiquement invalide (JSON valide, mauvaises données)
429 Too Many Requests     — Limite de débit dépassée

# Erreurs serveur
500 Internal Server Error — Échec inattendu (ne jamais exposer les détails)
502 Bad Gateway           — Le service en amont a échoué
503 Service Unavailable   — Surcharge temporaire, inclure Retry-After

Erreurs Courantes

# MAUVAIS : 200 pour tout
{ "status": 200, "success": false, "error": "Not found" }

# BON : Utiliser les codes d'état HTTP de manière sémantique
HTTP/1.1 404 Not Found
{ "error": { "code": "not_found", "message": "Utilisateur non trouvé" } }

# MAUVAIS : 500 pour les erreurs de validation
# BON : 400 ou 422 avec des détails au niveau du champ

# MAUVAIS : 200 pour les ressources créées
# BON : 201 avec l'en-tête Location
HTTP/1.1 201 Created
Location: /api/v1/users/abc-123

Format de Réponse

Réponse de Succès

{
  "data": {
    "id": "abc-123",
    "email": "[email protected]",
    "name": "Alice",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

Réponse de Collection (avec Pagination)

{
  "data": [
    { "id": "abc-123", "name": "Alice" },
    { "id": "def-456", "name": "Bob" }
  ],
  "meta": {
    "total": 142,
    "page": 1,
    "per_page": 20,
    "total_pages": 8
  },
  "links": {
    "self": "/api/v1/users?page=1&per_page=20",
    "next": "/api/v1/users?page=2&per_page=20",
    "last": "/api/v1/users?page=8&per_page=20"
  }
}

Réponse d'Erreur

{
  "error": {
    "code": "validation_error",
    "message": "La validation de la requête a échoué",
    "details": [
      {
        "field": "email",
        "message": "Doit être une adresse e-mail valide",
        "code": "invalid_format"
      },
      {
        "field": "age",
        "message": "Doit être compris entre 0 et 150",
        "code": "out_of_range"
      }
    ]
  }
}

Variantes d'Enveloppe de Réponse

// Option A : Enveloppe avec wrapper de données (recommandé pour les API publiques)
interface ApiResponse<T> {
  data: T;
  meta?: PaginationMeta;
  links?: PaginationLinks;
}

interface ApiError {
  error: {
    code: string;
    message: string;
    details?: FieldError[];
  };
}

// Option B : Réponse plate (plus simple, courante pour les API internes)
// Succès : retourner directement la ressource
// Erreur : retourner l'objet d'erreur
// Distinguer par le code d'état HTTP

Pagination

Basée sur le Décalage (Simple)

GET /api/v1/users?page=2&per_page=20

# Implémentation
SELECT * FROM users
ORDER BY created_at DESC
LIMIT 20 OFFSET 20;

Avantages : Facile à implémenter, prend en charge "sauter à la page N" Inconvénients : Lent sur les grands décalages (OFFSET 100000), incohérent avec les insertions simultanées

Basée sur le Curseur (Évolutive)

GET /api/v1/users?cursor=eyJpZCI6MTIzfQ&limit=20

# Implémentation
SELECT * FROM users
WHERE id > :cursor_id
ORDER BY id ASC
LIMIT 21;  -- en récupérer un de plus pour déterminer has_next

{
  "data": [...],
  "meta": {
    "has_next": true,
    "next_cursor": "eyJpZCI6MTQzfQ"
  }
}

Avantages : Performances cohérentes quelle que soit la position, stable avec les insertions simultanées Inconvénients : Impossible de sauter à une page arbitraire, le curseur est opaque

Quand Utiliser Quoi

Cas d'utilisation	Type de Pagination
Tableaux de bord d'administration, petits ensembles de données (<10K)	Décalage
Défilement infini, flux, grands ensembles de données	Curseur
API publiques	Curseur (par défaut) avec décalage (optionnel)
Résultats de recherche	Décalage (les utilisateurs s'attendent à des numéros de page)

Filtrage, Tri et Recherche

Filtrage

# Égalité simple
GET /api/v1/orders?status=active&customer_id=abc-123

# Opérateurs de comparaison (utiliser la notation par crochets)
GET /api/v1/products?price[gte]=10&price[lte]=100
GET /api/v1/orders?created_at[after]=2025-01-01

# Valeurs multiples (séparées par des virgules)
GET /api/v1/products?category=electronics,clothing

# Champs imbriqués (notation par points)
GET /api/v1/orders?customer.country=US

Tri

# Champ unique (préfixe - pour décroissant)
GET /api/v1/products?sort=-created_at

# Champs multiples (séparés par des virgules)
GET /api/v1/products?sort=-featured,price,-created_at

Recherche en Texte Intégral

# Paramètre de requête de recherche
GET /api/v1/products?q=wireless+headphones

# Recherche par champ spécifique
GET /api/v1/users?email=alice

Ensembles de Champs Épars

# Retourner uniquement les champs spécifiés (réduit la charge utile)
GET /api/v1/users?fields=id,name,email
GET /api/v1/orders?fields=id,total,status&include=customer.name

Authentification et Autorisation

Authentification par Jeton

# Jeton Bearer dans l'en-tête Authorization
GET /api/v1/users
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

# Clé API (pour serveur à serveur)
GET /api/v1/data
X-API-Key: sk_live_abc123

Modèles d'Autorisation

// Niveau ressource : vérifier la propriété
app.get("/api/v1/orders/:id", async (req, res) => {
  const order = await Order.findById(req.params.id);
  if (!order) return res.status(404).json({ error: { code: "not_found" } });
  if (order.userId !== req.user.id) return res.status(403).json({ error: { code: "forbidden" } });
  return res.json({ data: order });
});

// Basé sur les rôles : vérifier les autorisations
app.delete("/api/v1/users/:id", requireRole("admin"), async (req, res) => {
  await User.delete(req.params.id);
  return res.status(204).send();
});

Limitation de Débit

En-têtes

HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000

# Lorsque dépassé
HTTP/1.1 429 Too Many Requests
Retry-After: 60
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Limite de débit dépassée. Réessayez dans 60 secondes."
  }
}

Niveaux de Limite de Débit

Niveau	Limite	Fenêtre	Cas d'utilisation
Anonyme	30/min	Par IP	Points de terminaison publics
Authentifié	100/min	Par utilisateur	Accès API standard
Premium	1000/min	Par clé API	Plans API payants
Interne	10000/min	Par service	Service à service

Versioning

Versioning par Chemin d'URL (Recommandé)

/api/v1/users
/api/v2/users

Avantages : Explicite, facile à router, mise en cache possible Inconvénients : L'URL change entre les versions

Versioning par En-tête

GET /api/users
Accept: application/vnd.myapp.v2+json

Avantages : URL propres Inconvénients : Plus difficile à tester, facile à oublier

Stratégie de Versioning

1. Commencez par /api/v1/ — ne versionnez pas avant d'en avoir besoin
2. Maintenez au maximum 2 versions actives (actuelle + précédente)
3. Calendrier de dépréciation :
   - Annoncez la dépréciation (préavis de 6 mois pour les API publiques)
   - Ajoutez l'en-tête Sunset : Sunset: Sat, 01 Jan 2026 00:00:00 GMT
   - Retournez 410 Gone après la date de dépréciation
4. Les modifications non cassantes ne nécessitent pas une nouvelle version :
   - Ajout de nouveaux champs aux réponses
   - Ajout de nouveaux paramètres de requête optionnels
   - Ajout de nouveaux points de terminaison
5. Les modifications cassantes nécessitent une nouvelle version :
   - Supprimer ou renommer des champs
   - Changer les types de champs
   - Changer la structure d'URL
   - Changer la méthode d'authentification

Modèles d'Implémentation

TypeScript (Route API Next.js)

import { z } from "zod";
import { NextRequest, NextResponse } from "next/server";

const createUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(1).max(100),
});

export async function POST(req: NextRequest) {
  const body = await req.json();
  const parsed = createUserSchema.safeParse(body);

  if (!parsed.success) {
    return NextResponse.json({
      error: {
        code: "validation_error",
        message: "La validation de la requête a échoué",
        details: parsed.error.issues.map(i => ({
          field: i.path.join("."),
          message: i.message,
          code: i.code,
        })),
      },
    }, { status: 422 });
  }

  const user = await createUser(parsed.data);

  return NextResponse.json(
    { data: user },
    {
      status: 201,
      headers: { Location: `/api/v1/users/${user.id}` },
    },
  );
}

Python (Django REST Framework)

from rest_framework import serializers, viewsets, status
from rest_framework.response import Response

class CreateUserSerializer(serializers.Serializer):
    email = serializers.EmailField()
    name = serializers.CharField(max_length=100)

class UserSerializer(serializers.ModelSerializer):
    class Meta:
        model = User
        fields = ["id", "email", "name", "created_at"]

class UserViewSet(viewsets.ModelViewSet):
    serializer_class = UserSerializer
    permission_classes = [IsAuthenticated]

    def get_serializer_class(self):
        if self.action == "create":
            return CreateUserSerializer
        return UserSerializer

    def create(self, request):
        serializer = CreateUserSerializer(data=request.data)
        serializer.is_valid(raise_exception=True)
        user = UserService.create(**serializer.validated_data)
        return Response(
            {"data": UserSerializer(user).data},
            status=status.HTTP_201_CREATED,
            headers={"Location": f"/api/v1/users/{user.id}"},
        )

Go (net/http)

func (h *UserHandler) CreateUser(w http.ResponseWriter, r *http.Request) {
    var req CreateUserRequest
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        writeError(w, http.StatusBadRequest, "invalid_json", "Corps de requête invalide")
        return
    }

    if err := req.Validate(); err != nil {
        writeError(w, http.StatusUnprocessableEntity, "validation_error", err.Error())
        return
    }

    user, err := h.service.Create(r.Context(), req)
    if err != nil {
        switch {
        case errors.Is(err, domain.ErrEmailTaken):
            writeError(w, http.StatusConflict, "email_taken", "E-mail déjà enregistré")
        default:
            writeError(w, http.StatusInternalServerError, "internal_error", "Erreur interne")
        }
        return
    }

    w.Header().Set("Location", fmt.Sprintf("/api/v1/users/%s", user.ID))
    writeJSON(w, http.StatusCreated, map[string]any{"data": user})
}

Liste de Vérification pour la Conception d'API

Avant de livrer un nouveau point de terminaison :

• L'URL de la ressource suit les conventions de nommage (pluriel, kebab-case, pas de verbes)
• Méthode HTTP correcte utilisée (GET pour les lectures, POST pour les créations, etc.)
• Codes d'état appropriés retournés (pas 200 pour tout)
• Entrée validée avec un schéma (Zod, Pydantic, Bean Validation)
• Les réponses d'erreur suivent un format standard avec codes et messages
• Pagination implémentée pour les points de terminaison de liste (curseur ou décalage)
• Authentification requise (ou explicitement marquée comme publique)
• Autorisation vérifiée (l'utilisateur ne peut accéder qu'à ses propres ressources)
• Limitation de débit configurée
• La réponse ne divulgue pas de détails internes (traces de pile, erreurs SQL)
• Nommage cohérent avec les points de terminaison existants (camelCase vs snake_case)
• Documenté (spécification OpenAPI/Swagger mise à jour)