# 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`.

```python
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.

<p class="callout info">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.</p>

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

<p class="callout success">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.</p>

### Comparatif

<table id="bkmrk-code-firstdesign-fir"><thead><tr><th></th><th>Code-first</th><th>Design-first</th></tr></thead><tbody><tr><td>Point de départ</td><td>Le code</td><td>Le contrat</td></tr><tr><td>Synchronisation</td><td>Automatique</td><td>Discipline et outils de validation</td></tr><tr><td>Travail en parallèle</td><td>Difficile</td><td>Naturel</td></tr><tr><td>Adapté à…</td><td>Une API interne, une petite équipe, un prototype</td><td>Une API publique, plusieurs équipes, des partenaires</td></tr></tbody></table>

<p class="callout warning">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.</p>