Nommage des routes, verbes HTTP, codes de réponse, pagination et filtres
Utilisez les flĂšches, cliquez ou glissez pour naviguer
1. Comprendre une API REST
Sa philosophie et ses principes
2. ConnaĂźtre les verbes HTTP
GET, POST, PUT, PATCH, DELETE
3. Nommer les routes correctement
Ressources au pluriel, IDs dans l'URL
4. Choisir le bon code HTTP
200, 201, 204, 400, 401, 404, 422
5. Pagination et filtres
Via query params (?page, ?limit, ?search)
6. Différence REST vs RPC
Quand utiliser chaque style
Qu'est-ce qu'une API ?
Partir de ce que vous connaissez (applis mobiles, sites web)
REST : un style d'architecture
Pas un framework â des conventions que tout dev reconnaĂźt
Les verbes HTTP
GET, POST, PUT, PATCH, DELETE â chacun un rĂŽle prĂ©cis
Nommage des routes
Ressources au pluriel, pas de verbe dans l'URL
Codes de réponse HTTP
200, 201, 204, 400, 401, 404, 422
Live coding : CRUD Express
Construire un CRUD avec les bons verbes et codes
Application Programming Interface
Un intermédiaire qui permet à deux applications de communiquer
đ±
App mobile
Météo, réseau social
đ
Site web
Dashboard, e-commerce
đ
IoT / Services
Paiement, météo, IA
đĄ L'API est comme un serveur dans un restaurant : vous passez commande, le serveur apporte le plat.
âïž
Météo
Votre app météo appelle une API pour récupérer les prévisions
đł
Paiement Stripe
Quand vous payez en ligne, Stripe est contacté via son API
đ±
Réseau social
Scroll infini = votre app demande les posts suivants
đ€
ChatGPT / IA
Chaque requĂȘte Ă ChatGPT passe par une API REST
REST = REpresentational State Transfer
Ce n'est pas un framework ni une bibliothĂšque â c'est un ensemble de conventions
â REST est partout
GitHub, Stripe, Twitter, Google Maps â 90% des API modernes
â Tout dev le reconnaĂźt
MĂȘmes conventions = courbe d'apprentissage rĂ©duite
đŻ Objectif : rendre votre API prĂ©visible et cohĂ©rente
1. Ressources
Tout est une ressource (articles, utilisateurs, produits)
2. Verbes HTTP = actions
GET pour lire, POST pour créer, DELETE pour supprimer
3. URLs = noms, pas verbes
/createArticle â POST /articles
4. Sans état (Stateless)
Chaque requĂȘte contient tout ce qu'il faut â pas de session serveur
5. Codes de réponse standards
Le code HTTP dit tout : succÚs, erreur, accÚs refusé...
Chacun a un rÎle précis
Le verbe dit l'action
L'URL dit la ressource
Deux informations, une seule requĂȘte
Lire / Récupérer
Jamais d'effet de bord â peut ĂȘtre appelĂ© 100x
Créer
Envoie des donnĂ©es dans le body â crĂ©e une ressource
Remplacer
Remplace totalement une ressource existante
Modifier partiellement
Met Ă jour un ou plusieurs champs
Supprimer
DĂ©truit la ressource â pas de body en retour
Liste des articles
GET /api/articles
// Réponse 200 OK
{
"data": [
{ "id": 1, "title": "REST 101" },
{ "id": 2, "title": "HTTP Verbs" }
]
}
Un article spécifique
GET /api/articles/42
// Réponse 200 OK
{
"id": 42,
"title": "REST 101",
"content": "..."
}
â GET est idempotent : 10 appels = 1 appel, pas de double crĂ©ation
La requĂȘte
POST /api/articles
Content-Type: application/json
{
"title": "Nouvel article",
"content": "Contenu..."
}
La réponse
201 Created
Location: /api/articles/43
{
"id": 43,
"title": "Nouvel article"
}
â ïž POST n'est pas idempotent : 2 appels = 2 articles créés
PUT
Remplacement total
PUT /api/articles/5
// Body requis : TOUS les champs
{ "title": "X", "content": "Y" }
Si on oublie content, il devient null
PATCH
Modification partielle
PATCH /api/articles/5
// Body : juste les champs Ă modifier
{ "title": "X" }
content reste inchangĂ© â
đĄ RĂšgle : PATCH pour les mises Ă jour partielles, PUT seulement si vous renvoyez TOUT l'objet
La requĂȘte
DELETE /api/articles/42
// Pas de body nécessaire
// L'ID est dans l'URL
La réponse
204 No Content
// Pas de body en retour
// Le 204 dit tout : "C'est fait"
â ïž DELETE est idempotent : DELETE 2x de suite sur le mĂȘme ID â mĂȘme rĂ©sultat (404 la 2e fois si dĂ©jĂ supprimĂ©)
Le verbe donne l'action, l'URL donne la ressource
Jamais de verbe dans l'URL
// â Ă Ă©viter : verbes dans l'URL
GET /api/createArticle
POST /api/deleteUser
GET /api/getArticles
// â Conventions REST : ressources au pluriel
POST /api/articles
DELETE /api/articles/42
GET /api/articles
| Verbe | Route | Action | Code |
|---|---|---|---|
| GET | /articles | Lister tous les articles | 200 |
| GET | /articles/:id | Lire un article | 200 |
| POST | /articles | Créer un article | 201 |
| PUT | /articles/:id | Remplacer un article | 200 |
| PATCH | /articles/:id | Modifier un article | 200 |
| DELETE | /articles/:id | Supprimer un article | 204 |
đĄ Ressources toujours au pluriel : /articles, /users, /products
La carte de score de votre API
2xx
SuccĂšs
4xx
Erreur client
5xx
Erreur serveur
OK
RequĂȘte rĂ©ussie â utilisĂ© pour GET, PUT, PATCH
Created
Ressource créée â utilisĂ© pour POST
Inclure le header Location avec l'URL de la nouvelle ressource
No Content
SuccĂšs mais pas de body â utilisĂ© pour DELETE
Bad Request
La requĂȘte est mal formĂ©e, champs manquants ou invalides
Unauthorized
Authentification manquante ou invalide
Forbidden
Authentifié mais pas les droits suffisants
Not Found
Ressource introuvable â route ou ID inconnu
Unprocessable Entity
Validation échouée (ex: email déjà pris)
// Quel code retourner ?
RequĂȘte reçue
âââ La requĂȘte est invalide ?
âââ â 400 Bad Request
âââ Pas authentifiĂ© ?
âââ â 401 Unauthorized
âââ Ressource inexistante ?
âââ â 404 Not Found
âââ Validation Ă©chouĂ©e ?
âââ â 422 Unprocessable Entity
âââ Tout est OK
âââ POST (crĂ©ation)
âââ â 201 Created
âââ DELETE
âââ â 204 No Content
âââ GET / PUT / PATCH
âââ â 200 OK
Toujours paginer les routes de liste !
?page et ?limit dans l'URL, jamais dans le body
GET /api/articles?page=2&limit=10
// Réponse :
{
"data": [...],
"meta": {
"page": 2,
"limit": 10,
"total": 97,
"totalPages": 10
}
}
đĄ Valeurs par dĂ©faut : page=1, limit=20
Filtres = query params supplémentaires
?search=, ?category=, ?status= â faciles Ă ajouter
GET /api/articles?search=REST&category=tech&status=published&page=1&limit=10
â Filtres dans l'URL
Partageable, bookmarkable
â Filtres dans le body
Impossible Ă partager en un clic
CRUD Express avec les bons verbes et codes
On va construire une API REST ensemble
Bun + Express + TypeScript
đ api-articles/
âââ package.json
âââ src/
âââ index.ts
âââ types.ts
âââ articles.json
// types.ts
export interface Article {
id: number;
title: string;
content: string;
}
â bun init -y && bun add express
import { Router, Request, Response } from 'express';
import type { Article } from './types';
const router = Router();
let articles: Article[] = [];
// â Pagination via query params
router.get('/', (req: Request, res: Response) => {
const page = Number(req.query.page) || 1;
const limit = Number(req.query.limit) || 10;
const start = (page - 1) * limit;
const data = articles.slice(start, start + limit);
const total = articles.length;
res.status(200).json({ data, meta: { page, limit, total } });
});
// â DĂ©tail d'un article
router.get('/:id', (req: Request, res: Response) => {
const id = Number(req.params.id);
const article = articles.find(a => a.id === id);
if (!article) return res.status(404).json({ error: 'Article non trouvé' });
res.status(200).json(article);
});
let nextId = 1;
router.post('/', (req: Request, res: Response) => {
const { title, content } = req.body as Pick<Article, 'title' | 'content'>;
// â Validation â 422 si invalide
if (!title || !content) {
return res.status(422).json({
error: 'Champs title et content requis'
});
}
const newArticle: Article = { id: nextId++, title, content };
articles.push(newArticle);
// â 201 Created + Location header
res
.status(201)
.location(`/articles/${newArticle.id}`)
.json(newArticle);
});
// â PATCH : modification partielle â 200
router.patch('/:id', (req: Request, res: Response) => {
const id = Number(req.params.id);
const article = articles.find(a => a.id === id);
if (!article) return res.status(404).json({ error: 'Not Found' });
Object.assign(article, req.body); // â partiel
res.status(200).json(article);
});
// â DELETE : suppression â 204 No Content
router.delete('/:id', (req: Request, res: Response) => {
const id = Number(req.params.id);
const index = articles.findIndex(a => a.id === id);
if (index === -1) return res.status(404).json({ error: 'Not Found' });
articles.splice(index, 1);
res.status(204).send(); // â pas de body
});
REST
â Ressources = noms
â Verbes HTTP standardisĂ©s
â URLs = /users/42
â DĂ©couverte naturelle
â 90% des API CRUD
POST /api/articles
DELETE /api/articles/5
RPC
â Actions = verbes dans l'URL
â POST pour tout (ou GET)
â URLs = /createUser
â Plus flexible pour actions complexes
â Parfait pour les micro-services
POST /api/createArticle
POST /api/deleteArticle
â REST pour :
CRUD classique (articles, users, produits), API publiques, quand les ressources sont bien définies
â RPC pour :
Actions spécifiques (envoyer un email, générer un PDF), commandes, micro-services internes
// REST
POST /api/orders
// RPC (mieux pour actions)
POST /api/orders/5/ship
POST /api/orders/5/cancel
đĄ RĂšgle : REST pour 90% des cas, RPC quand l'action ne colle pas Ă un CRUD
Le verbe dit l'action, l'URL dit la ressource
Jamais de verbe dans l'URL
POST
= crĂ©er â 201
GET
= lire â 200
DELETE
= supprimer â 204
Pagination via ?page=&limit=
Toujours dans les query params, jamais dans le body
REST = standard pour 90% des API CRUD
RPC pour actions spécifiques non-CRUD
â Mettre des verbes dans l'URL
/createArticle
POST /articles â
â Utiliser 200 pour tout
// POST â 201, DELETE â 204, PAS 200
â Chaque code a une signification prĂ©cise
â Oublier la pagination
// GET /articles sans ?page â 1000 rĂ©sultats d'un coup
â Toujours paginer les routes de liste
â PUT au lieu de PATCH
// PUT remplace TOUT, PATCH modifie partiellement
â Utilisez PATCH pour les mises Ă jour partielles
Verbes
GET, POST, PUT, PATCH, DELETE
Chacun son rĂŽle
Routes
Ressources au pluriel
Jamais de verbe dans l'URL
Codes
200, 201, 204, 400, 404, 422
Chaque situation a son code
đŻ Une API REST bien conçue se comprend d'elle-mĂȘme
Le verbe donne l'action, l'URL donne la ressource, le code donne le résultat
Les conventions REST sont la base de toutes les API modernes
Pratiquez en construisant votre propre CRUD !
GET, POST, PUT, PATCH, DELETE â Ă vous de jouer