Cours Vibe coding avec Claude Code · Module 14: Clone de Pinterest

Routes commerciales : des routes d'API avec la spécification issue d'un entretien

12 min de lecture
Dans cette leçon12

Les tableaux sont déjà dans la base mais les pins suivent encore l'ancienne route. La page d'accueil et GET /api/pins lisent la liste de lib/pins.ts, il est impossible d'ajouter un nouveau pin, et impossible de récupérer un pin par son identifiant. Les routes d'API sont un contrat avec quiconque y frappe : qui peut ajouter un pin, quels champs on accepte, quel code reçoit un inconnu, comment on découpe la liste en pages. Si tu écris seulement "fais l'API des pins", Claude prendra chacune de ces décisions en silence, et tu ne les découvriras que dans le code. D'où l'entretien d'abord, comme dans les leçons 0_5 et 1_6, et la construction seulement à partir du contrat écrit.

Ce que tu vas apprendre

  • mener un entretien dont naît un SPEC.md pour l'API ;
  • commencer la construction dans une session neuve, en mode plan, à partir de la seule spécification ;
  • reconnaître l'affectation de masse (data: body) et la remplacer par une liste de champs autorisés ;
  • distinguer les réponses 400, 401, 404 et 201 et les prouver avec curl ;
  • juger quand GraphQL vaut mieux que des routes REST.

Demande pour Claude Code : l'entretien

Passe la session en mode Manual : l'entretien ne change rien, et Claude ne demandera ton accord qu'avant d'écrire un fichier.

Demande pour Claude Code :

Je veux des routes d'API pour les pins de Treasure Map : une liste
paginée, l'ajout d'un pin et un pin par id. Le client de la base est
dans @lib/prisma.ts, les tableaux dans @lib/boards.ts, la session dans
@lib/session.ts. Mène un entretien avec moi, trois questions à la fois
au maximum : qui peut faire quoi, quels codes d'erreur on renvoie,
comment fonctionne la pagination, quels champs on accepte du client et
lesquels fixe le serveur. Ensuite écris SPEC.md : objectif, routes,
champs, erreurs, ce qu'on ne fait pas, comment on vérifiera. N'écris
pas de code.

Les bonnes pratiques de Claude Code décrivent ce schéma ainsi : Claude revient avec des questions à choix multiples sur ce que tu n'as pas encore décidé, et il continue de poser des questions jusqu'à ce que les réponses forment une spécification. Il pose les questions avec l'outil AskUserQuestion. Tu choisis une réponse toute faite ou tu écris la tienne dans la ligne Other. Pour une API, les questions peuvent ressembler à ceci :

1. Qui peut ajouter un pin ?
   a) toute personne connectée  b) seulement le propriétaire du tableau  c) tout le monde
2. Que reçoit un client qui envoie un champ hors de la liste ?
   a) 400 avec le nom du champ  b) le champ est ignoré en silence
3. Comment découpe-t-on la liste des pins en pages ?
   a) curseur comme dans la leçon 13_1  b) numéro de page

À chaque question, tu réponds en pensant à l'attaquant, pas seulement au navigateur : un champ que tu n'as pas prévu, quelqu'un finira par l'envoyer.

Ce que Claude a écrit : SPEC.md

Ouvre SPEC.md dans Cursor. Ton fichier aura d'autres mots, mais il doit consigner les mêmes décisions. La partie la plus importante peut ressembler à ceci :

## Routes
- GET /api/pins?cursor=<id> : 12 pins et nextCursor (null à la fin), pour tous.
- GET /api/pins/<id> : un pin ou 404. L'id est un texte, jamais un nombre.
- POST /api/pins : seulement connecté (401). Champs : title, src (depuis /pins/),
  width, height, dominantColor, tags (5 au maximum).
## Fixé par le serveur
- id, ownerId et author depuis la session, createdAt. Champ hors liste : 400 avec son nom.
## Ce qu'on ne fait pas
- modifier et supprimer des pins, envoyer des images.

La spécification dit "quoi", pas "comment" : on n'y trouve ni noms de fichiers ni ordre de travail. La section "Fixé par le serveur" est la partie la plus importante de ce contrat, et tu y reviendras pendant la revue.

Session neuve et plan tiré de la spécification

La conversation de l'entretien est pleine d'idées rejetées. La documentation de Claude Code conseille de construire dans une session neuve, avec un contexte propre et une définition écrite de "terminé". Tape /clear : l'ancienne conversation reste disponible pour être reprise, et la nouvelle ne connaît que ce que tu lui donnes. Puis :

/plan Construis les routes des pins selon @SPEC.md. D'abord les tests de
validation de POST /api/pins : champ hors liste, ownerId dans le corps,
titre vide, nombres donnés sous forme de textes, pas de session. Ensuite
le code. Validation par un schéma Zod, comme dans la leçon 6_1. La page
d'accueil doit prendre la première page de pins dans la même fonction
que la route. À la fin : tests, lint, npx tsc --noEmit et npm run build.

Avec @SPEC.md, Claude reçoit le contrat sans le bruit de la conversation précédente. Dans le plan, vérifie que les tests passent avant le code et que le propriétaire du pin vient de getCurrentUserId(). Claude ajoutera au projet la bibliothèque zod.

Ce que Claude a écrit : la liste des champs autorisés

Ouvre lib/pinInput.ts. Une liste de champs autorisés (whitelist) énumère tout ce que le client peut envoyer. Ce qui n'y figure pas ne passe pas :

// lib/pinInput.ts
export const pinInputSchema = z.strictObject(
  {
    title: z.string().trim().min(1, "Donne un titre.").max(100, "Le titre fait 100 caractères au maximum."),
    src: z.string().startsWith("/pins/", "L'image doit se trouver dans /pins/."),
    width: pixels,
    height: pixels,
    dominantColor: z.string().regex(/^#[0-9a-f]{6}$/, "Couleur au format #rrggbb."),
    tags: z.array(z.string().trim().min(1).max(30)).max(5, "5 tags au maximum.").default([]),
  },
  { error: (issue) => (issue.code === "unrecognized_keys" ? `Champs inconnus : ${issue.keys.join(", ")}` : undefined) },
);

Tu connais les schémas Zod depuis la leçon 6_1. z.strictObject ne diffère de z.object que sur un point : une clé inconnue est une erreur, pas un champ ignoré en silence. Le dernier argument transforme cette erreur en message français avec le nom du champ. pixels est une constante de ce fichier : un entier de 1 à 10000, donc le texte "600" ne passe pas. startsWith("/pins/") n'admet que les images de notre port. Cinq tests veillent sur ces règles.

L'erreur typique de l'agent : data: body

La route la plus courte que l'agent sache écrire, et celle de l'ancienne version de cette leçon, ressemble à ceci :

// app/api/pins/route.ts (version de l'agent)
const body = await request.json();
const pin = await prisma.pin.create({ data: body });

C'est l'affectation de masse (mass assignment) : le client décide de chaque colonne. Nous avons passé à create un corps avec "ownerId": "capitaine" et "author": "Capitaine Barbe-Rousse", et Prisma a docilement enregistré le pin sur le compte du capitaine, alors que le corps pouvait venir de Polly. Le champ role, notre modèle l'a justement rejeté avec l'erreur Unknown argument, qui dans la route se termine par un code 500. Mais dans une table d'utilisateurs avec une colonne role, la même ligne permettrait à n'importe qui de s'attribuer les droits d'administrateur. Le piège existe aussi en version avec décomposition : dans { ownerId: viewerId, ...body }, le corps écrase le propriétaire, car c'est ce qui vient après qui gagne. Chez nous, le pin a de nouveau atterri chez le capitaine.

Ce que Claude a écrit : POST

Ouvre app/api/pins/route.ts. Les contrôles se suivent, et seul ce qui est passé par le schéma arrive à la base :

// app/api/pins/route.ts
export async function POST(request: Request) {
  const viewerId = await getCurrentUserId();
  if (!viewerId) return Response.json({ error: "Connecte-toi." }, { status: 401 });
  const body = await request.json().catch(() => null);
  if (body === null) return Response.json({ error: "Envoie le pin sous forme d'objet JSON." }, { status: 400 });
  const result = pinInputSchema.safeParse(body);
  if (!result.success) {
    const { formErrors, fieldErrors } = z.flattenError(result.error);
    return Response.json({ error: formErrors[0] ?? "Corrige les champs.", fields: fieldErrors }, { status: 400 });
  }
  const pin = await createPin(result.data, viewerId);
  return Response.json(pin, { status: 201 });
}

createPin de lib/pinStore.ts assemble les données de result.data avec ownerId et author tirés de la session. Le code 400 porte toujours une raison, et fields indique quel champ corriger, ce que tu connais des formulaires de la leçon 6_1. La route ne révèle pas non plus les détails d'une erreur de la base, car rien de non vérifié n'arrive jusqu'à la base. Le test qui mérite le plus d'être lu :

// app/api/pins/route.test.ts
test("ownerId dans le corps : 400 et rien n'arrive à la base", async () => {
  const res = await post({ ...valid, ownerId: "capitaine" });
  expect(res.status).toBe(400);
  expect(await res.json()).toMatchObject({ error: "Champs inconnus : ownerId" });
  expect(db.create).not.toHaveBeenCalled();
});

Le test remplace @/lib/prisma et @/lib/session par vi.mock, comme dans la leçon 8_3, donc il tourne sans base. La dernière ligne vérifie l'essentiel : rien n'est arrivé jusqu'à create.

Ce que Claude a écrit : un pin et la 404

Ouvre app/api/pins/[id]/route.ts :

// app/api/pins/[id]/route.ts
export async function GET(_request: Request, { params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  const pin = await getPin(id);
  if (!pin) return Response.json({ error: "Ce pin n'existe pas." }, { status: 404 });
  return Response.json(pin);
}

Dans Next.js 16, params est une promesse (Promise), donc await est obligatoire. Les identifiants sont des textes (p07 ou un cmw... généré), donc pas de parseInt ici. L'ancienne version de la leçon en faisait un nombre : parseInt("cmw...") donne NaN, et Prisma répond par une exception et un code 500. L'absence de pin est une 404 avec une raison, pas un 200 avec null, sur lequel le client trébucherait.

La liste fonctionne avec le curseur de la leçon 13_1, sauf que le curseur est maintenant l'id du premier pin de la page suivante. getPinPage récupère 13 pins : douze sont rendus, et le treizième indique la page suivante. La page d'accueil appelle la même fonction, donc PinFeed n'a rien remarqué.

La revue du capitaine

  1. Seulement les champs autorisés. Cherche dans le projet data: body et ...body. Il n'y en a aucun dans les routes, et create reçoit result.data et les champs de la session.
  2. Des codes avec une raison. Avec npm run dev en marche, envoie un pin avec le propriétaire de quelqu'un d'autre :
curl -s -b demo-user=perroquet -H 'Content-Type: application/json' -d '{"title":"Carte du marché","src":"/pins/skarb-10.jpg","width":600,"height":700,"dominantColor":"#986848","ownerId":"capitaine"}' localhost:3000/api/pins

Chez nous, il est revenu {"error":"Champs inconnus : ownerId","fields":{}} avec le code 400. Le même corps sans ownerId a donné 201, sans le cookie 401, et GET /api/pins/42 comme GET /api/pins/inexistant ont donné 404. 3. Les paramètres. await params dans chaque route avec [id], et aucun parseInt sur l'identifiant. 4. Propriétaire tiré de la session. Cherche body.ownerId. L'erreur typique de l'agent est d'accepter le propriétaire depuis le formulaire "parce que c'est plus pratique pour tester".

/security-review comme habitude

Les routes d'écriture sont l'endroit où tu fais toujours la revue de sécurité de la leçon 8_7 : commit, puis /security-review. La revue ne lit que les changements de la branche, comparés à la branche par défaut d'origin. Nous n'avons pas lancé cette commande sur cette branche, donc nous ne montrons aucun rapport. Chaque signalement, tu le vérifies dans Cursor, comme dans la leçon 8_7. Rappelle-toi aussi que la session démo de la leçon 11_3 est un cookie non signé que n'importe qui peut fixer lui-même. Si le rapport n'en dit rien, cela ne veut pas dire que le problème n'existe pas. Une revue peut passer à côté d'une trouvaille réelle mais peu grave. La vraie connexion est montrée par la leçon facultative sur Supabase.

Et GraphQL ?

L'ancienne version de cette leçon promettait GraphQL dans son titre, sans le montrer. Honnêtement : GraphQL est une autre façon de construire une API. Au lieu de nombreuses adresses, il n'y en a qu'une, et le client envoie une requête qui énumère exactement les champs voulus, y compris ceux des objets liés. Le serveur décrit ses données par un schéma de types. Cela vaut la peine quand de nombreux clients différents, par exemple une application mobile et un site, ont besoin de tranches différentes des mêmes données imbriquées. Une seule API remplace alors une douzaine de routes faites sur mesure. En contrepartie, cela coûte plus de travail : un schéma, des fonctions de résolution pour chaque champ, une protection contre les requêtes trop profondes et un cache plus difficile, puisque tout passe par une seule adresse. Treasure Map n'a qu'un client et quelques routes, donc REST dans des route handlers suffit.

Étape suivante

Quand la revue passe, demande un commit "Routes des pins selon SPEC.md". Le petit pas suivant commence par la spécification, pas par le code : "Ajoute à SPEC.md la suppression d'un pin : seulement le propriétaire, un inconnu reçoit 404, puis construis-la dans une session neuve". Dans l'éditeur ci-dessous t'attend un testeur de routes : envoie des requêtes avec différents corps et un cookie, puis active la version de l'agent avec data: body et regarde chez qui atterrit le pin dans la table.

Retiens ceci : une route commerciale sans garde est une invitation pour les pirates, donc tu écris le contrat avant que les caravanes partent et tu ne laisses entrer que la marchandise de la liste.

Code de cette leçon : App.tsx
// Les routes commerciales en miniature : envoie une requête aux routes des pins et regarde le code de la réponse
import { useState } from 'react';

interface Pin {
  id: string;
  title: string;
  src: string;
  width: number;
  height: number;
  dominantColor: string;
  tags: string[];
  ownerId: string;
}

interface ApiResult {
  status: number;
  body: unknown;
  pins: Pin[];
}

const START: Pin[] = [
  { id: 'p07', title: 'Lagune', src: '/pins/skarb-07.jpg', width: 600, height: 800, dominantColor: '#a8c808', tags: ['lagune'], ownerId: 'perroquet' },
  { id: 'p10', title: 'Vieille carte', src: '/pins/skarb-10.jpg', width: 600, height: 700, dominantColor: '#986848', tags: ['carte'], ownerId: 'capitaine' },
];

const ALLOWED = ['title', 'src', 'width', 'height', 'dominantColor', 'tags'];
const COLUMNS = [...ALLOWED, 'id', 'ownerId', 'author', 'createdAt'];

const VALID = '{"title": "Carte du marché", "src": "/pins/skarb-10.jpg", "width": 600, "height": 700, "dominantColor": "#986848"}';

const PRESETS = [
  { label: 'GET un pin', method: 'GET', path: '/api/pins/p07', body: '' },
  { label: 'GET pin absent', method: 'GET', path: '/api/pins/42', body: '' },
  { label: 'POST valide', method: 'POST', path: '/api/pins', body: VALID },
  { label: 'POST avec ownerId', method: 'POST', path: '/api/pins', body: VALID.replace('}', ', "ownerId": "capitaine"}') },
  { label: 'POST avec role', method: 'POST', path: '/api/pins', body: VALID.replace('}', ', "role": "admin"}') },
  { label: 'POST champs invalides', method: 'POST', path: '/api/pins', body: '{"title": "  ", "src": "https://example.com/a.jpg", "width": "600", "height": 700, "dominantColor": "red"}' },
];

function isPositiveInt(value: unknown) {
  return Number.isInteger(value) && (value as number) >= 1 && (value as number) <= 10000;
}

// Liste des champs autorisés, comme pinInputSchema de la leçon : tout ce qui est hors liste donne une erreur 400
function validate(body: Record<string, unknown>) {
  const unknownKeys = Object.keys(body).filter((key) => !ALLOWED.includes(key));
  const fields: Record<string, string> = {};
  if (typeof body.title !== 'string' || body.title.trim() === '') fields.title = 'Donne un titre.';
  if (typeof body.src !== 'string' || !body.src.startsWith('/pins/')) fields.src = "L'image doit se trouver dans /pins/.";
  if (!isPositiveInt(body.width)) fields.width = 'Donne un nombre de pixels.';
  if (!isPositiveInt(body.height)) fields.height = 'Donne un nombre de pixels.';
  if (typeof body.dominantColor !== 'string' || !/^#[0-9a-f]{6}$/.test(body.dominantColor)) fields.dominantColor = 'Couleur au format #rrggbb.';
  return { unknownKeys, fields };
}

function send(method: string, path: string, rawBody: string, session: string, agentVersion: boolean, pins: Pin[]): ApiResult {
  if (method === 'GET') {
    const id = path.split('/').pop() ?? '';
    const pin = pins.find((p) => p.id === id);
    return pin ? { status: 200, body: pin, pins } : { status: 404, body: { error: "Ce pin n'existe pas." }, pins };
  }
  let body: unknown = null;
  try {
    body = JSON.parse(rawBody);
  } catch {
    body = null;
  }
  if (agentVersion) {
    // version de l'agent : prisma.pin.create({ data: body }), sans session et sans liste de champs
    const data = (body ?? {}) as Record<string, unknown>;
    const extra = Object.keys(data).find((key) => !COLUMNS.includes(key));
    if (extra) return { status: 500, body: { error: 'Unknown argument ' + extra + '.' }, pins };
    const created = { tags: [], author: '', ...data, id: 'nouveau' + (pins.length + 1) } as unknown as Pin;
    if (!created.ownerId) return { status: 500, body: { error: 'Argument ownerId is missing.' }, pins };
    return { status: 201, body: { id: created.id }, pins: [...pins, created] };
  }
  if (!session) return { status: 401, body: { error: 'Connecte-toi.' }, pins };
  if (body === null || typeof body !== 'object' || Array.isArray(body)) {
    return { status: 400, body: { error: "Envoie le pin sous forme d'objet JSON." }, pins };
  }
  const input = body as Record<string, unknown>;
  const { unknownKeys, fields } = validate(input);
  if (unknownKeys.length > 0) return { status: 400, body: { error: 'Champs inconnus : ' + unknownKeys.join(', ') }, pins };
  if (Object.keys(fields).length > 0) return { status: 400, body: { error: 'Corrige les champs.', fields }, pins };
  const created: Pin = {
    id: 'nouveau' + (pins.length + 1),
    title: String(input.title).trim(),
    src: String(input.src),
    width: Number(input.width),
    height: Number(input.height),
    dominantColor: String(input.dominantColor),
    tags: Array.isArray(input.tags) ? input.tags.map(String) : [],
    ownerId: session, // propriétaire tiré de la session, jamais du corps
  };
  return { status: 201, body: { id: created.id }, pins: [...pins, created] };
}

export default function App() {
  const [pins, setPins] = useState<Pin[]>(START);
  const [preset, setPreset] = useState(0);
  const [rawBody, setRawBody] = useState(PRESETS[0].body);
  const [session, setSession] = useState('perroquet');
  const [agentVersion, setAgentVersion] = useState(false);
  const [result, setResult] = useState<ApiResult | null>(null);
  const request = PRESETS[preset];

  function choose(i: number) {
    setPreset(i);
    setRawBody(PRESETS[i].body);
    setResult(null);
  }

  function submit() {
    const next = send(request.method, request.path, rawBody, session, agentVersion, pins);
    setPins(next.pins);
    setResult(next);
  }

  return (
    <div className="min-h-screen space-y-4 bg-amber-50 p-4 text-zinc-900">
      <h1 className="text-xl font-bold">Routes commerciales : testeur des routes des pins</h1>
      <div className="flex flex-wrap gap-2">
        {PRESETS.map((p, i) => (
          <button key={p.label} type="button" onClick={() => choose(i)} className={i === preset ? 'rounded-full bg-red-600 px-3 py-1 text-sm text-white' : 'rounded-full bg-zinc-200 px-3 py-1 text-sm'}>
            {p.label}
          </button>
        ))}
      </div>
      <p className="font-mono text-sm">
        {request.method} {request.path}
      </p>
      {request.method === 'POST' && (
        <label className="block text-sm">
          Corps de la requête (JSON, tu peux le modifier) :
          <textarea value={rawBody} onChange={(e) => setRawBody(e.target.value)} rows={4} className="mt-1 w-full rounded border border-zinc-300 bg-white p-2 font-mono text-xs" />
        </label>
      )}
      <div className="flex flex-wrap items-center gap-3 text-sm">
        <label className="flex items-center gap-2">
          Cookie de session :
          <select value={session} onChange={(e) => setSession(e.target.value)} className="rounded border border-zinc-300 px-2 py-1">
            <option value="perroquet">perroquet</option>
            <option value="capitaine">capitaine</option>
            <option value="">aucun</option>
          </select>
        </label>
        <label className="flex items-center gap-2">
          <input type="checkbox" checked={agentVersion} onChange={(e) => setAgentVersion(e.target.checked)} />
          Version de l'agent : data: body
        </label>
        <button type="button" onClick={submit} className="rounded-full bg-red-600 px-4 py-2 font-semibold text-white">
          Envoyer
        </button>
      </div>
      {result && (
        <div role="status" className={result.status < 300 ? 'rounded-xl bg-emerald-100 p-3 text-sm' : 'rounded-xl bg-red-100 p-3 text-sm'}>
          <p className="font-bold">Status {result.status}</p>
          <p className="break-all font-mono text-xs">{JSON.stringify(result.body)}</p>
        </div>
      )}
      <table className="w-full rounded-xl bg-white text-left text-sm">
        <caption className="text-left font-semibold">Table Pin dans la base</caption>
        <thead>
          <tr>
            <th className="p-1">id</th>
            <th className="p-1">title</th>
            <th className="p-1">ownerId</th>
          </tr>
        </thead>
        <tbody>
          {pins.map((pin) => (
            <tr key={pin.id} className="border-t border-zinc-200">
              <td className="p-1 font-mono">{pin.id}</td>
              <td className="p-1">{pin.title}</td>
              <td className="p-1">{pin.ownerId}</td>
            </tr>
          ))}
        </tbody>
      </table>
    </div>
  );
}

Tu as repéré une erreur dans cette leçon ?

Teste tes connaissances

Réponds aux questions de cette leçon. Choisis une réponse pour voir tout de suite si elle est correcte.

  1. 1. Comment ajouter une route GET /api/pins/[id] dans l'App Router ?

  2. 2. D'où le gestionnaire de app/api/pins/[id]/route.ts tire-t-il l'id du pin ?

Tâches pratiques dans le jeu

  • Clique dans l'ordre

    Clique sur les éléments pour construire la ligne qui répond par le code 404 quand le pin n'existe pas :

  • Tri horizontal

    Ordonne les éléments d'une ligne qui renvoie le pin créé avec le statut 201 :

  • Éditeur de code

    Crée des endpoints d'API REST

  1. QuestionQuiz : la route GET d'un seul pin
  2. Clique dans l'ordreConstruction : la 404 pour un pin absent
  3. Remets dans l'ordreTri : le statut 201 dans POST
  4. Exercice de codePratique : les routes API
  5. QuestionQuiz : l'id dans une route dynamique

Articles utiles