Créer une REST API avec Claude Code | Guide pratique pour débutants

« Je ne sais pas par où commencer avec les REST API » — c’est exactement ce que je ressentais au début.

Lire la documentation me semblait trop abstrait. Je ne savais pas ce que je devais construire concrètement. C’est alors que j’ai commencé à utiliser Claude Code et que j’ai réalisé que « construire quelque chose qui fonctionne d’abord, apprendre ensuite » est l’approche la plus rapide.

Dans ce guide, nous allons de zéro connaissance des REST API jusqu’à une API entièrement fonctionnelle — étape par étape, avec Claude Code. Tous les extraits de code sont prêts à être copiés-collés.

---

Qu’est-ce qu’une REST API ? (En 3 lignes)

Une REST API est une convention pour manipuler des ressources (données) sur le web via HTTP.

Navigateur/App  →  Requête HTTP  →  Serveur (API)
                ←  Réponse JSON  ←

Pour une API de gestion d’utilisateurs, cela ressemble à ceci :

Objectif	Méthode HTTP	URL
Obtenir tous les utilisateurs	GET	/users
Obtenir un utilisateur	GET	/users/123
Créer un utilisateur	POST	/users
Mettre à jour un utilisateur	PUT	/users/123
Supprimer un utilisateur	DELETE	/users/123

Une fois cela compris, vous êtes prêt à commencer à construire avec Claude Code.

---

Configuration de l’environnement

Nous utiliserons Hono — un framework web TypeScript léger. Il est plus type-safe qu’Express et fonctionne parfaitement avec Claude Code.

mkdir my-first-api
cd my-first-api
npm init -y
npm install hono
npm install -D typescript @types/node ts-node
npx tsc --init

Créez src/index.ts et demandez à Claude Code :

claude -p "
Crée un boilerplate de REST API avec Hono dans src/index.ts.
- Démarre le serveur sur le port 3000
- Ajoute un endpoint GET /health pour les health checks
- Retourne des réponses JSON
Commande d'exécution : npx ts-node src/index.ts
"

Claude Code générera quelque chose comme ceci :

// src/index.ts
import { Hono } from "hono";
import { serve } from "@hono/node-server";

const app = new Hono();

app.get("/health", (c) => {
  return c.json({ status: "ok", timestamp: new Date().toISOString() });
});

serve({ fetch: app.fetch, port: 3000 }, () => {
  console.log("Server running at http://localhost:3000");
});

npx ts-node src/index.ts
# → Server running at http://localhost:3000

curl http://localhost:3000/health
# → {"status":"ok","timestamp":"2026-04-27T07:30:00.000Z"}

Ça fonctionne ? C’est votre point de départ pour les REST API.

---

Step 1 : Créer un CRUD de base

Ensuite, construisons une API pour gérer une liste de Todos. Demandez à Claude Code :

claude -p "
Ajoute des endpoints CRUD de Todo à src/index.ts.
- GET  /todos         — Lister tous les todos
- GET  /todos/:id     — Obtenir un todo
- POST /todos         — Créer (title: string requis)
- PUT  /todos/:id     — Mettre à jour (title: string)
- DELETE /todos/:id   — Supprimer

Gérer les données dans un tableau en mémoire.
Type Todo : { id: string, title: string, done: boolean, createdAt: string }
Générer l'id avec crypto.randomUUID()
"

Code généré :

import { Hono } from "hono";
import { serve } from "@hono/node-server";

const app = new Hono();

// Stockage de données en mémoire
type Todo = { id: string; title: string; done: boolean; createdAt: string };
let todos: Todo[] = [];

// Lister tous les todos
app.get("/todos", (c) => c.json(todos));

// Obtenir un todo
app.get("/todos/:id", (c) => {
  const todo = todos.find((t) => t.id === c.req.param("id"));
  if (!todo) return c.json({ error: "Not found" }, 404);
  return c.json(todo);
});

// Créer
app.post("/todos", async (c) => {
  const body = await c.req.json();
  if (!body.title) return c.json({ error: "title is required" }, 400);
  const todo: Todo = {
    id: crypto.randomUUID(),
    title: body.title,
    done: false,
    createdAt: new Date().toISOString(),
  };
  todos.push(todo);
  return c.json(todo, 201);
});

// Mettre à jour
app.put("/todos/:id", async (c) => {
  const idx = todos.findIndex((t) => t.id === c.req.param("id"));
  if (idx === -1) return c.json({ error: "Not found" }, 404);
  const body = await c.req.json();
  todos[idx] = { ...todos[idx], ...body };
  return c.json(todos[idx]);
});

// Supprimer
app.delete("/todos/:id", (c) => {
  const idx = todos.findIndex((t) => t.id === c.req.param("id"));
  if (idx === -1) return c.json({ error: "Not found" }, 404);
  todos.splice(idx, 1);
  return c.json({ message: "Deleted" });
});

serve({ fetch: app.fetch, port: 3000 }, () => {
  console.log("Server running at http://localhost:3000");
});

Testez-le :

# Créer un Todo
curl -X POST http://localhost:3000/todos \
  -H "Content-Type: application/json" \
  -d '{"title": "Essayer Claude Code"}'

# Lister tous les todos
curl http://localhost:3000/todos

# Supprimer (utilisez l'id retourné ci-dessus)
curl -X DELETE http://localhost:3000/todos/<id>

---

Step 2 : Ajouter la validation

« Un titre vide peut toujours être créé » ou « N’importe quelle chaîne fonctionne comme ID » — la validation prévient ces problèmes. Demandez à Claude Code :

claude -p "
Ajoute une validation avec zod pour POST /todos et PUT /todos/:id.
- title: string, 1-100 caractères
- done: (PUT uniquement) boolean
Retourner une erreur 400 avec un message d'erreur spécifique en cas d'échec de validation
"

npm install zod

Claude Code ajoute des schémas zod :

import { z } from "zod";

const CreateTodoSchema = z.object({
  title: z.string().min(1, "Le titre doit avoir au moins 1 caractère").max(100, "Le titre ne peut pas dépasser 100 caractères"),
});

const UpdateTodoSchema = z.object({
  title: z.string().min(1).max(100).optional(),
  done: z.boolean().optional(),
});

// POST /todos (avec validation)
app.post("/todos", async (c) => {
  const body = await c.req.json().catch(() => ({}));
  const result = CreateTodoSchema.safeParse(body);
  if (!result.success) {
    return c.json({ error: result.error.flatten().fieldErrors }, 400);
  }
  const todo: Todo = {
    id: crypto.randomUUID(),
    title: result.data.title,
    done: false,
    createdAt: new Date().toISOString(),
  };
  todos.push(todo);
  return c.json(todo, 201);
});

Vérifiez les erreurs de validation :

# Créer sans titre → devrait générer une erreur
curl -X POST http://localhost:3000/todos \
  -H "Content-Type: application/json" \
  -d '{}'
# → {"error":{"title":["Le titre doit avoir au moins 1 caractère"]}}

---

Step 3 : Unifier la gestion des erreurs

Actuellement, chaque endpoint retourne les erreurs dans des formats différents. Laissez Claude Code standardiser cela :

claude -p "
Unifie la gestion des erreurs.
- Format de réponse d'erreur commun : { error: { code: string, message: string } }
- 404: NOT_FOUND
- 400: VALIDATION_ERROR
- 500: INTERNAL_SERVER_ERROR
Implémenter un gestionnaire d'erreurs global avec le onError de Hono
"

// Définition du type d'erreur
class AppError extends Error {
  constructor(
    public code: string,
    public message: string,
    public statusCode: number = 400
  ) {
    super(message);
  }
}

// Gestionnaire d'erreurs global
app.onError((err, c) => {
  if (err instanceof AppError) {
    return c.json(
      { error: { code: err.code, message: err.message } },
      err.statusCode as any
    );
  }
  console.error(err);
  return c.json(
    { error: { code: "INTERNAL_SERVER_ERROR", message: "Une erreur inattendue s'est produite" } },
    500
  );
});

// Utilisation
app.get("/todos/:id", (c) => {
  const todo = todos.find((t) => t.id === c.req.param("id"));
  if (!todo) throw new AppError("NOT_FOUND", "Todo introuvable", 404);
  return c.json(todo);
});

---

Step 4 : Générer automatiquement la documentation Swagger UI

Une fois votre API construite, vous avez besoin de documentation. Claude Code peut tout configurer en quelques minutes :

claude -p "
Utilise @hono/swagger-ui et @hono/zod-openapi pour
ajouter Swagger UI sous /docs.
Ajoute des schémas OpenAPI aux endpoints existants.
"

npm install @hono/swagger-ui @hono/zod-openapi

Une fois terminé, visitez http://localhost:3000/docs pour voir la documentation de votre API.

---

Le workflow de développement d’API avec Claude Code (résumé)

Voici le flux que j’utilise au quotidien :

1. Dire à Claude Code "J'ai besoin d'une API qui fait X"
    ↓
2. Vérifier et tester le code généré
    ↓
3. Itérer : "Corriger ça", "Ajouter de la validation", etc.
    ↓
4. git commit quand les tests passent

Mon premier obstacle (expérience réelle)

Quand j’ai construit ma première API, j’ai complètement omis la gestion des erreurs et j’ai dû tout ajouter après coup — ce qui m’a pris une éternité. Maintenant, j’ajoute simplement « inclure la gestion des erreurs » à mon prompt dès le départ, et le code sort propre immédiatement. L’astuce avec Claude Code, c’est de donner toutes les exigences dès le début.

---

3 pièges courants

Piège 1 : Ignorer les erreurs de parsing JSON

// ❌ Les erreurs ici passent inaperçues
const body = await c.req.json();

// ✅ Attraper les échecs de parsing
const body = await c.req.json().catch(() => null);
if (!body) return c.json({ error: "Invalid JSON" }, 400);

Piège 2 : Confondre 404 et 400

400 : La requête elle-même est incorrecte (erreur de validation, champ requis manquant)
404 : La ressource n'existe pas (ID introuvable)
422 : Le format de la requête est correct mais ne peut pas être traité

Demandez à Claude Code « Dois-je retourner 404 ou 400 ici ? » et il vous donnera la bonne réponse.

Piège 3 : Tout stocker en mémoire

Le code de ce guide utilise un tableau en mémoire à des fins de démonstration. Les données disparaissent lorsque vous redémarrez le serveur. En production, vous aurez besoin d’une base de données comme PostgreSQL ou MongoDB. Dites simplement à Claude Code « Stocke ça dans SQLite au lieu de la mémoire » et il gérera la migration.

---

Prochaines étapes

Une fois que vous maîtrisez les bases des REST API, essayez ceci :

Étape	Que faire
Base de données	SQLite → PostgreSQL (avec Prisma)
Authentification	Ajouter l’authentification JWT
Tests	Écrire des tests d’API avec vitest
Déploiement	Publier sur Vercel / Cloudflare Workers

Pour tout cela, dites simplement à Claude Code « ajouter X » et la base sera prête en quelques minutes. Construisez d’abord quelque chose qui fonctionne — c’est le chemin le plus rapide.

Articles connexes

• Conception, implémentation et tests REST API avec Claude Code à toute vitesse
• Guide complet pour débutants Claude Code
• Meilleures pratiques de sécurité avec Claude Code