Convention de réponses HTTP – API REST (.NET)

Format standard des réponses

Toutes les réponses de l’API utilisent un format JSON homogène.

Réponse de succès

{ "success": true, "data": {}, "message": "Opération effectuée avec succès", "traceId": "00-5fdc9c9b1b0b5a4f-01" }

Réponse d’erreur (RFC7807 / ProblemDetails recommandé en .NET)

{ "type": "https://httpstatuses.com/400", "title": "Bad Request", "status": 400, "detail": "Le champ email est invalide", "instance": "/users", "errors": { "email": ["Le format de l'email est incorrect"] }, "traceId": "00-5fdc9c9b1b0b5a4f-01" }

> En .NET, utiliser ProblemDetails ou ValidationProblemDetails pour rester conforme aux standards.

---

Table de correspondance des statuts HTTP

Code	Nom	Quand l’utiliser	Corps de réponse
200	OK	Requête réussie avec résultat	data
201	Created	Ressource créée	data + location
204	No Content	Succès sans contenu	vide
301/302	Redirect	Redirection ressource	vide
400	Bad Request	Paramètres invalides	ProblemDetails
401	Unauthorized	Non authentifié	ProblemDetails
403	Forbidden	Accès refusé	ProblemDetails
404	Not Found	Ressource inexistante	ProblemDetails
409	Conflict	Conflit métier	ProblemDetails
422	Unprocessable Entity	Validation métier échouée	ValidationProblemDetails
429	Too Many Requests	Rate limit	ProblemDetails
500	Internal Server Error	Exception serveur	ProblemDetails
503	Service Unavailable	Maintenance / dépendance KO	ProblemDetails

---

Détail par statut

---

200 — OK

Description
La requête a été traitée avec succès. Exemple

{ "success": true, "data": { "id": 12, "name": "Jean Dupont" }, "message": "Utilisateur récupéré" }

---

201 — Created

Description
Une ressource a été créée. Headers

Location: /api/users/12

Exemple

{ "success": true, "data": { "id": 12 }, "message": "Utilisateur créé" }

---

204 — No Content

Description
Succès sans contenu (DELETE ou PUT sans retour) Corps

(vide)

---

301 / 302 / 307 — Redirect

Description
La ressource a changé d’URL. Headers

Location: /api/v2/users/12

---

400 — Bad Request

Description
La requête est mal formée ou paramètres invalides. Exemple

{ "type": "https://httpstatuses.com/400", "title": "Bad Request", "status": 400, "detail": "Paramètre 'page' invalide", "errors": { "page": ["La page doit être supérieure à 0"] } }

---

401 — Unauthorized

Description
Token absent ou invalide. Exemple

{ "type": "https://httpstatuses.com/401", "title": "Unauthorized", "status": 401, "detail": "Authentification requise" }

---

403 — Forbidden

Description
Utilisateur authentifié mais sans permission.

{ "type": "https://httpstatuses.com/403", "title": "Forbidden", "status": 403, "detail": "Vous n'avez pas les droits nécessaires" }

---

404 — Not Found

Description
La ressource demandée n’existe pas.

{ "type": "https://httpstatuses.com/404", "title": "Not Found", "status": 404, "detail": "Utilisateur introuvable" }

---

409 — Conflict

Description
Violation d’une règle métier (doublon, état invalide…)

{ "type": "https://httpstatuses.com/409", "title": "Conflict", "status": 409, "detail": "Un utilisateur avec cet email existe déjà" }

---

422 — Unprocessable Entity (validation métier)

Description
Les données sont valides techniquement mais refusées fonctionnellement.

{ "type": "https://httpstatuses.com/422", "title": "Validation Error", "status": 422, "errors": { "birthDate": ["L'utilisateur doit être majeur"] } }

---

429 — Too Many Requests

Description
Limite de requêtes atteinte (rate limiting)

{ "type": "https://httpstatuses.com/429", "title": "Too Many Requests", "status": 429, "detail": "Trop de requêtes, réessayez plus tard" }

---

500 — Internal Server Error

Description
Erreur inattendue côté serveur. ⚠️ Ne jamais exposer la stacktrace en production.

{ "type": "https://httpstatuses.com/500", "title": "Internal Server Error", "status": 500, "detail": "Une erreur interne est survenue", "traceId": "00-5fdc9c9b1b0b5a4f-01" }

---

503 — Service Unavailable

Description
Dépendance indisponible (DB, API externe, maintenance…)

{ "type": "https://httpstatuses.com/503", "title": "Service Unavailable", "status": 503, "detail": "Service temporairement indisponible" }

---

Bonnes pratiques .NET

Utiliser ProblemDetails automatiquement

Dans Program.cs :

builder.Services.AddProblemDetails(); app.UseExceptionHandler(); app.UseStatusCodePages();

Retourner les erreurs

return Results.Problem( title: "Utilisateur introuvable", statusCode: StatusCodes.Status404NotFound );

Validation automatique

[ApiController] public class UsersController : ControllerBase

ASP .NET retournera automatiquement un 400 ValidationProblemDetails.

---

Recommandations

• Toujours fournir traceId
• Ne jamais exposer les exceptions internes
• Uniformiser tous les contrôleurs
• Mapper les exceptions métiers → codes HTTP cohérents
• Préférer 422 pour règles métier plutôt que 400