Conventions REST

Nommage des routes, verbes HTTP, codes de réponse, pagination et filtres

Utilisez les flĂšches, cliquez ou glissez pour naviguer

Objectifs de la leçon

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

Plan du cours

1

Qu'est-ce qu'une API ?

Partir de ce que vous connaissez (applis mobiles, sites web)

2

REST : un style d'architecture

Pas un framework — des conventions que tout dev reconnaüt

3

Les verbes HTTP

GET, POST, PUT, PATCH, DELETE — chacun un rĂŽle prĂ©cis

4

Nommage des routes

Ressources au pluriel, pas de verbe dans l'URL

5

Codes de réponse HTTP

200, 201, 204, 400, 401, 404, 422

6

Live coding : CRUD Express

Construire un CRUD avec les bons verbes et codes

Qu'est-ce qu'une API ?

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.

Les API dans votre quotidien

☁

Météo

Votre app météo appelle une API pour récupérer les prévisions

GET /api/weather?city=Paris

💳

Paiement Stripe

Quand vous payez en ligne, Stripe est contacté via son API

POST /v1/charges

đŸ“±

Réseau social

Scroll infini = votre app demande les posts suivants

GET /api/posts?page=2

đŸ€–

ChatGPT / IA

Chaque requĂȘte Ă  ChatGPT passe par une API REST

POST /v1/chat/completions

REST : un style d'architecture

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

Les principes REST

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

Les verbes HTTP

Chacun a un rÎle précis

Le verbe dit l'action

L'URL dit la ressource

Deux informations, une seule requĂȘte

Les 5 verbes HTTP

GET

Lire / Récupérer

Jamais d'effet de bord — peut ĂȘtre appelĂ© 100x

200
POST

Créer

Envoie des donnĂ©es dans le body — crĂ©e une ressource

201
PUT

Remplacer

Remplace totalement une ressource existante

200
PATCH

Modifier partiellement

Met Ă  jour un ou plusieurs champs

200
DELETE

Supprimer

DĂ©truit la ressource — pas de body en retour

204

GET : Lire des données

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

POST : Créer une ressource

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 vs PATCH : quelle différence ?

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

DELETE : Supprimer une ressource

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Ă©)

Nommage des routes

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

Tableau récapitulatif

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

Les codes de réponse HTTP

La carte de score de votre API

2xx

SuccĂšs

4xx

Erreur client

5xx

Erreur serveur

Codes de succĂšs (2xx)

200

OK

RequĂȘte rĂ©ussie — utilisĂ© pour GET, PUT, PATCH

201

Created

Ressource créée — utilisĂ© pour POST

Inclure le header Location avec l'URL de la nouvelle ressource

204

No Content

SuccĂšs mais pas de body — utilisĂ© pour DELETE

Codes d'erreur (4xx)

400

Bad Request

La requĂȘte est mal formĂ©e, champs manquants ou invalides

401

Unauthorized

Authentification manquante ou invalide

403

Forbidden

Authentifié mais pas les droits suffisants

404

Not Found

Ressource introuvable — route ou ID inconnu

422

Unprocessable Entity

Validation échouée (ex: email déjà pris)

Arbre de décision

// 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

Pagination via query params

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 via query params

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

?search=REST&page=2

Partageable, bookmarkable

❌ Filtres dans le body

POST /articles (body: {search:"REST"})

Impossible Ă  partager en un clic

Live Coding

CRUD Express avec les bons verbes et codes

On va construire une API REST ensemble

Bun + Express + TypeScript

Structure du projet

📁 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

GET : Liste + Détail

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);

});

POST : Créer un 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 & DELETE

// ✅ 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 vs RPC

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

Quand choisir REST ou RPC ?

✅ 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

Points clés à retenir

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

PiÚges courants à éviter

❌ 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

Récapitulatif

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

Questions ?

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