Introduction aux API REST
Introduction aux API REST
Concevoir et consommer des interfaces web standardisées
REST (Representational State Transfer) est un style d'architecture pour la conception de services
web. Une API REST expose des ressources accessibles via le protocole HTTP. Ce document
présente les principes, les méthodes et les conventions permettant de bâtir une API claire et
cohérente.
Sommaire
■ 1. Les principes de REST
■ 2. Les méthodes HTTP
■ 3. Structurer les URL
■ 4. Les codes de statut HTTP
■ 5. Exemple de réponse JSON
■ 6. Bonnes pratiques
Documentation technique Page 1
Introduction aux API REST
1. Les principes de REST
■ Architecture client-serveur : séparation des responsabilités.
■ Sans état : chaque requête contient toute l'information nécessaire.
■ Interface uniforme : ressources identifiées par des URL.
■ Représentations : les données circulent souvent au format JSON.
2. Les méthodes HTTP
Chaque opération sur une ressource correspond à une méthode HTTP.
■ GET : lire une ou plusieurs ressources.
■ POST : créer une nouvelle ressource.
■ PUT : remplacer une ressource existante.
■ PATCH : modifier partiellement une ressource.
■ DELETE : supprimer une ressource.
3. Structurer les URL
Les URL doivent désigner des ressources (des noms), pas des actions. On utilise le pluriel et une
hiérarchie logique.
GET /articles # liste des articles
GET /articles/42 # un article précis
POST /articles # créer un article
PUT /articles/42 # mettre à jour
DELETE /articles/42 # supprimer
4. Les codes de statut HTTP
■ 2xx : succès (200 OK, 201 Created, 204 No Content).
■ 4xx : erreur du client (400, 401, 403, 404).
■ 5xx : erreur du serveur (500, 503).
Renvoyer le bon code de statut aide le client à interpréter la réponse.
5. Exemple de réponse JSON
{
"id": 42,
"titre": "Premier article",
"publie": true,
"tags": ["web", "api"]
}
Documentation technique Page 2
Introduction aux API REST
6. Bonnes pratiques
■ Versionner l'API (ex. /v1/articles).
■ Documenter les points d'entrée (OpenAPI / Swagger).
■ Gérer la pagination pour les grandes collections.
■ Sécuriser l'accès avec des jetons (JWT, OAuth).
Documentation technique Page 3