Qu'est-ce que le code d’état HTTP 201 ? Signification, exemples et quand l'utiliser

Tous les codes d’état HTTP ne sont pas identiques. Certains confirment simplement qu’une requête serveur a réussi, tandis que d’autres ont une signification particulière. Le code d’état 201 vous indique que le serveur a créé avec succès une nouvelle ressource. En général, cela fait suite à une requête POST, ou parfois à une requête PUT, le plus souvent utilisée avec les services API.

Dans cet article, nous expliquerons en détail ce que signifie le code de réponse 201 « Created », nous examinerons des exemples tirés d’API REST et des formulaires de navigateur, et le comparerons à d’autres codes d’état HTTP similaires.

Qu’est-ce que le code d’état HTTP 201 ?

Le code d’état 201 signifie qu’une requête a réussi et qu’une nouvelle ressource a été créée.

Selon la spécification HTTP/1.1, un code de réponse serveur 201 approprié doit inclure un champ d’en-tête de localisation.

Cela doit pointer vers l’URI spécifique de la ressource nouvellement créée ou principale. Il peut également inclure un corps de réponse contenant des détails sur les données demandées.

Ce comportement rend le 201 différent des autres codes de réponse serveur. Par exemple :

• 200 OK signifie simplement que la requête a réussi et renvoie les données demandées, mais ne crée pas nécessairement une nouvelle entité.
• 201 Created indique explicitement qu’une nouvelle ressource existe désormais à l’URI de la requête effective, ou à une autre adresse de redirection fournie dans l‘en-tête de localisation.

En pratique, le code 201 est le plus souvent utilisé dans les API REST où une requête POST ajoute un nouvel utilisateur, un article de blog, un fichier téléchargé ou toute autre ressource cible. Il peut également s’appliquer aux formulaires web, tels qu’une page d’inscription, où un serveur répond avec succès à la requête et où une nouvelle entité est enregistrée dans la base de données.

Quand utiliser le code 201 (et quand ne pas le faire)

Le code d’état 201 s’applique lorsque le serveur répond avec succès à une requête du client qui entraîne la création de quelque chose de nouveau. Ci-dessous, nous énumérerons les cas d’utilisation les plus courants.

Cas d’utilisation corrects

• Inscription d’utilisateur : La création d’un nouveau compte utilisateur renvoie un 201 Created accompagné d’un en-tête de localisation pointant vers la page de profil.
• Création d’article de blog : Publier un article de blog avec une requête POST devrait renvoyer un code 201 une fois l’article enregistré.
• Téléchargement de fichier : Lorsqu’un fichier téléchargé est stocké sur le serveur d’origine, le code de réponse devrait être 201 « Created » avec un lien vers la ressource cible.
• Commande d’e-commerce : Un processus de paiement où le serveur prépare une nouvelle entrée de commande peut renvoyer 201 plus un corps de réponse avec l’ID de la commande.

Cas d’utilisation incorrects

Le code 201 Created ne doit pas être utilisé si aucune nouvelle ressource n’a été générée. Les erreurs courantes incluent :

• Connexion ou authentification : Une requête a réussi, mais n’a pas ajouté de nouvelle entité. Le code d’état approprié est généralement 200 « OK ».
• Mise à jour des données existantes : Une requête PUT qui modifie une instance actuelle devrait renvoyer 200 « OK » ou 204 « No Content ».
• Requêtes de recherche : Le retour des données demandées n’implique pas la création de ressource ; 200 « OK » est correct.
• Tentatives de création en double : Si le serveur d’origine refuse de créer parce que l’identité du client existe déjà, renvoyez Conflit 409 .

L’utilisation d’un code de réponse incorrect peut semer la confusion chez l’agent utilisateur et entraîner des erreurs sémantiques ou des réponses invalides dans une API REST.

Exemple d’API : création d’un nouvel utilisateur

Le code d’état 201 apparaît le plus souvent dans les API lorsqu’une ressource nouvellement créée est renvoyée après une requête du client. Prenons un cas courant – la création d’un nouvel utilisateur dans API REST.

Voici par exemple un exemple de requête POST envoyée à api.example.com :

POST /users HTTP/1.1
Host: api.example.com
Content-Type: application/json
{
"name": "John Doe",
"email": "john@example.com"
}

Dans cette requête POST, l’agent utilisateur demande au serveur d’origine d’ajouter une nouvelle entité. Ci-dessous, vous pouvez voir une réponse courante du serveur :

HTTP/1.1 201 Created
Location: /users/123
Content-Type: application/json
{
"id": 123,
"name": "John Doe",
"email": "john@example.com"
}

Le code de réponse serveur 201 « Created » indique que la requête a réussi et qu’une nouvelle ressource a été ajoutée – un nouvel utilisateur, John Doe, son adresse e-mail, et un ID utilisateur respectif ont été créés avec succès.

Points clés dans cet exemple :

• Le champ d’en-tête de localisation fournit l’URI spécifique où la ressource principale créée est accessible.
• Le corps de la réponse renvoie les données demandées pour le nouvel utilisateur, confirmant la création de la ressource.
• La requête a été traitée avec succès en une seule étape : aucune méthode de requête supplémentaire ni adresse de redirection n’ont été nécessaires.

Il s’agit de la manière la plus correcte et la plus conforme aux normes d’utiliser le code de réponse HTTP 201 « Created » selon la spécification HTTP.

Exemple de navigateur : démonstration d’un formulaire d’inscription (scénario pratique)

Bien que le code d’état 201 soit le plus courant dans les API, vous pouvez le voir en action avec un simple formulaire web.

Examinons une page de démonstration d’inscription où un visiteur peut créer un nouveau compte utilisateur.

Lorsque le formulaire est soumis, le serveur d’origine traite la requête du client, stocke les données et renvoie la réponse 201 « Created ».

Dans notre démonstration :

1. Le visiteur saisit son nom, son adresse e-mail et son mot de passe.
2. Le serveur valide les champs de l’en-tête de la requête et enregistre les données en tant que nouvelle ressource dans la base de données.
3. Le code de réponse du serveur est 201 « Created », accompagné d’un en-tête de localisation pointant vers le nouveau profil.
4. Une page de confirmation affiche les détails de la ressource demandée, indiquant que la requête a été traitée avec succès.

Gardez à l’esprit qu’il est peu probable que vous voyiez des codes de réponse 201 sur l’interface utilisateur des sites web.

Cette démonstration vise à illustrer le processus qui se déroule généralement « en coulisses » lorsque le serveur traite les requêtes.

Vous pouvez également utiliser les outils Développeur et Réseau de votre navigateur pour observer l’utilisation du code d’état dans des applications réelles.

201 vs. autres codes d’état similaires

Le code de réponse HTTP 201 Created est souvent confondu avec d’autres codes de réussite. Voici comment il se compare à des réponses similaires :

201 vs 200 « OK »

• 200 « OK » signifie que la requête a réussi et que les données demandées sont renvoyées.
• Il n’indique pas qu’une ressource nouvellement créée existe.
• Par exemple : obtenir un article de blog ou mettre à jour une instance actuelle.

201 vs 202 « Accepted »

• 202 « Accepted » signifie que la requête du client a été reçue et peut être traitée plus tard.
• Il n’y a aucune garantie qu’une nouvelle entité soit créée pour le moment.
• Par exemple : soumettre un travail à une file d’attente pour traitement ultérieur, tel que  générer un PDF ou gérer un système de paiement numérique.

201 vs 204 « No Content »

• 204 « No Content » signifie que la requête a réussi et qu’il n’y a pas de corps de message à renvoyer.
• Il est souvent utilisé pour une requête PUT qui met à jour une ressource existante.
• Il n’implique ni en-tête de localisation ni nouvelle ressource.

Points clés à retenir sur le code d’état 201

Résumons les points principaux concernant le code 201 :

• Le code d’état HTTP 201 confirme que le serveur a répondu avec succès à une requête du client en créant une nouvelle ressource.
• Un code de réponse 201 approprié du serveur doit inclure un champ d’en-tête de localisation pointant vers l’URI spécifique de la ressource nouvellement créée et peut également renvoyer un corps de réponse avec des détails sur les données demandées.
• Le code de réponse 201 « Created » est le plus courant dans les API REST pour la création de ressources (nouvel utilisateur, article de blog, fichier téléchargé ou commande).
• Ne confondez pas 201 avec d’autres codes d’état HTTP tels que 200 « OK », 202 « Accepted », ou 204 « No Content » : chacun communique un résultat différent de la méthode de requête.
• L’utilisation du code d’état HTTP correct signifie que l’agent utilisateur peut gérer correctement la ressource demandée.

En résumé : 201 indique au client; « La requête a fonctionné, et une nouvelle ressource existe désormais ».