Anatomie d'une requête bien conçue
1 / 8
Méthode HTTP
GET lit sans effet de bord : la réponse peut être mise en cache et l'appel réessayé sans risque.
HTTP/1.1 200 OK{ "data": [ { "id": 7731, "total": 1250.0, "status": "open" }, { "id": 7702, "total": 980.5, "status": "open" } ], "hasMore": true, "nextCursor": "def456"}
Exemple illustratif
Conception de ressources RESTful
Bonnes pratiques de conception d'URI
- Utiliser des noms, pas des verbes :
/customerset non/getCustomers - Relations hiérarchiques :
/customers/123/orders - Noms de ressources au pluriel :
/productset non/product - Utiliser des tirets pour la lisibilité :
/customer-orderset non/customer_orders - URI en minuscules :
/customerset non/Customers
Méthodes HTTP et sémantique
| Méthode | Objectif | Idempotent | Exemple |
|---|---|---|---|
| GET | Récupérer ressource(s) | Oui | GET /customers/123 |
| POST | Créer nouvelle ressource | Non | POST /customers |
| PUT | Remplacer ressource entière | Oui | PUT /customers/123 |
| PATCH | Mise à jour partielle | Non | PATCH /customers/123 |
| DELETE | Supprimer ressource | Oui | DELETE /customers/123 |
Conception de réponse
Codes de statut HTTP
- 200 OK :GET, PUT, PATCH ou DELETE réussi
- 201 Created :POST réussi avec en-tête Location vers nouvelle ressource
- 204 No Content :Requête réussie sans corps de réponse
- 400 Bad Request :Syntaxe de requête invalide ou erreurs de validation
- 401 Unauthorized :Authentification requise
- 403 Forbidden :Authentifié mais non autorisé
- 404 Not Found :La ressource n'existe pas
- 409 Conflict :Conflit d'état de ressource (p. ex. doublon)
- 429 Too Many Requests :Limite de débit dépassée
- 500 Internal Server error :Erreur serveur non gérée
Format de réponse d'erreur
Des réponses d'erreur cohérentes améliorent l'expérience développeur :
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid email format",
"target": "email",
"details": [
{
"field": "email",
"message": "Must be a valid email address"
}
]
}
}Pagination, filtrage et tri
Stratégies de pagination
- Basé sur l'offset :
?skip=20&limit=10- Simple mais inefficace pour les grands ensembles de données - Basé sur curseur :
?cursor=abc123&limit=10- Efficace pour les données en temps réel - Basé sur page :
?page=3&pageSize=10- Convivial pour la pagination d'interface utilisateur
Inclure les métadonnées de pagination dans la réponse : totalCount, hasMore, nextCursor
Filtrage et tri
- Filtres simples :
?status=active&category=electronics - Opérateurs de comparaison :
?price[gte]=100&price[lte]=500 - Recherche plein texte :
?q=laptop&searchFields=name,description - Tri :
?sortBy=createdAt&order=desc - Sélection de champs :
?fields=id,name,email