api-design

Modèles de Conception d'API

Conventions et meilleures pratiques pour la conception d'API REST cohérentes et conviviales pour les développeurs.

Quand Activer

• Conception de nouveaux points de terminaison API
• Révision des contrats API existants
• Ajout de pagination, filtrage ou tri
• Implémentation de la gestion des erreurs pour les API
• Planification de la stratégie de versionnage des 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

# BIEN
/api/v1/team-members          # kebab-case pour les ressources composées
/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é

# MAL
/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 une ressource imbriquée

Méthodes HTTP et Codes de Statut

Sémantique des Méthodes

Méthode	Idempotente	Sûre	À utiliser pour
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 de Statut

# 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 Fréquentes

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

# BIEN : Utiliser les codes de statut HTTP de manière sémantique
HTTP/1.1 404 Not Found
{ "error": { "code": "not_found", "message": "User not found" } }

# MAL : 500 pour les erreurs de validation
# BIEN : 400 ou 422 avec détails au niveau du champ

# MAL : 200 pour les ressources créées
# BIEN : 201 avec 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": "Request validation failed",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address",
        "code": "invalid_format"
      },
      {
        "field": "age",
        "message": "Must be between 0 and 150",
        "code": "out_of_range"
      }
    ]
  }
}

Variantes de l'Enveloppe de Réponse

// Option A : Enveloppe avec wrapper data (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, courant pour les API internes)
// Succès : renvoyer directement la ressource
// Erreur : renvoyer l'objet d'erreur
// Distinguer par le code de statut 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, permet de "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 (Passerelle)

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 constantes 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 Quel Type

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 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 entre 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 l'ordre 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 Partiels (Sparse Fieldsets)

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

// Au niveau de la 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 permissions
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 la limite est dépassée
HTTP/1.1 429 Too Many Requests
Retry-After: 60
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds."
  }
}

Niveaux de Limitation 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

Versionnage

Versionnage par Chemin d'URL (Recommandé)

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

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

Versionnage 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 Versionnage

1. Commencez par /api/v1/ — ne versionnez que si nécessaire
2. Maintenez au maximum 2 versions actives (actuelle + précédente)
3. Calendrier de dépréciation :
   - Annoncer la dépréciation (préavis de 6 mois pour les API publiques)
   - Ajouter l'en-tête Sunset : Sunset: Sat, 01 Jan 2026 00:00:00 GMT
   - Renvoyer 410 Gone après la date de dépréciation
4. Les modifications non destructrices ne nécessitent pas une nouvelle version :
   - Ajouter de nouveaux champs aux réponses
   - Ajouter de nouveaux paramètres de requête optionnels
   - Ajouter de nouveaux points de terminaison
5. Les modifications destructrices nécessitent une nouvelle version :
   - Supprimer ou renommer des champs
   - Modifier les types de champs
   - Modifier la structure de l'URL
   - Modifier 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: "Request validation failed",
        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", "Invalid request body")
        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", "Email already registered")
        default:
            writeError(w, http.StatusInternalServerError, "internal_error", "Internal error")
        }
        return
    }

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

Checklist de Conception d'API

Avant de publier un nouveau point de terminaison :

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