Code-first ou design-first

Le contrat et le code doivent dire la même chose. Mais lequel écrit-on en premier ?

Code-first

On écrit le code, et le contrat est généré à partir de lui (annotations, types, décorateurs…).

C'est ce que fait FastAPI : les types Python et les modèles Pydantic suffisent à produire un contrat OpenAPI complet, disponible sur /openapi.json, avec sa documentation sur /docs.

from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI(title="API-ritif")

class ReviewCreate(BaseModel):
    rating: int = Field(ge=1, le=5)
    comment: str | None = Field(default=None, max_length=500)

@app.post("/v1/cocktails/{cocktail_id}/reviews", status_code=201)
def create_review(cocktail_id: int, review: ReviewCreate):
    ...

Rien d'autre à écrire : rating apparaît dans le contrat comme un entier entre 1 et 5.

• ✅ Le contrat est toujours synchronisé avec le code.
• ✅ Rapide pour démarrer.
• ❌ Le contrat n'existe qu'une fois le code écrit : le front attend le back.
• ❌ La conception de l'API est guidée par l'implémentation, pas par les besoins du client.

Tous les frameworks n'en sont pas capables : Flask ou Express (JavaScript) ne connaissent pas les types des données. Il faut ajouter des bibliothèques et des commentaires spéciaux, souvent oubliés lors des modifications.

Design-first

On écrit d'abord le contrat, on le fait valider par ceux qui vont l'utiliser, puis on code.

• ✅ On réfléchit à l'API du point de vue de ses clients.
• ✅ Le front et le back travaillent en parallèle : le front utilise un mock généré à partir du contrat (voir chapitre 7).
• ✅ Le contrat sert à générer des tests, des clients, de la validation.
• ❌ Il faut une discipline pour garder le code conforme au contrat.

Des outils vérifient les requêtes et les réponses directement à partir du contrat, par exemple Prism en mode proxy (chapitre 7). Le contrat devient du code exécutable.

Comparatif

Dans le TP des avis (chapitre 7), le contrat OpenAPI vous est fourni avant le code : c'est du design-first, et c'est lui qui fait foi.