HTTP Status 201 (Created)

HTTP Status 201 indicates that, as a result of an ‘HTTP POST’ request, one or more new resources have been successfully created on the server.

HTTP Status 201 indicates that, as a result of an ‘HTTP POST’ request, one or more new resources have been successfully created on the server. It is documented in the HTTP specification (RFC-7231) that can be consulted if more information is needed.

1. HTTP Headers

The response may contain URI in Location header field in the HTTP headers list, which can have a reference to the newly created resource.

Also, the response payload also may include an entity containing a list of resource characteristics and location(s) from which the user or user agent can choose the one most appropriate.

The entity format is specified by the media type given in the Content-Type header field.

The origin server MUST create the resource before returning the 201 status code. If the action cannot be carried out immediately, the server SHOULD respond with 202 (Accepted) response instead.

2. Example

Here’s an example of a request and response for a 201 status code. In this instance, the client initiates a POST request with the intent of creating a new user in the system. The server effectively carries out the user creation process and, in response, conveys a status code of 201 Created, affirming the successful execution of the request and the inception of a novel resource.

Furthermore, the response is accompanied by a ‘Location‘ header, delineating the URL where the recently generated resource can be found. Additionally, a JSON payload is included in the response, providing comprehensive information regarding the newly created user, encompassing details like the user’s unique ID, name, email, and the date of their creation.

POST /api/v1/users HTTP/1.1
Content-Type: application/json

  "name": "John Doe",
  "email": "[email protected]",
  "password": "s3cr3t"
HTTP/1.1 201 Created
Content-Type: application/json
Cache-Control: no-cache

  "id": 123,
  "name": "John Doe",
  "email": "[email protected]",
  "created_at": "2023-06-11T08:30:00Z"

3. Lost Update Problem

HTTP 201 response MAY contain an ETag response header field indicating the current value of the entity tag for the requested variant just created.

Lost update problem happens when multiple people edit a resource without knowledge of each others’ changes.

ETag header field can be used in later conditional requests to prevent the “lost update” problem. In this scenario, the last person to update a resource “wins”, and previous updates are lost.

ETags can be used in combination with the ‘If-Match‘ header to let the server decide if a resource should be updated. If ETag does not match then the server informs the client via a ‘412 (Precondition Failed)‘ response.

In the following request, The server receives a request to update the product with the ETag “etag123.”

POST /products/123/update
If-Match: "etag123"

Content-Type: application/json

    "productName": "Smartphone X",
    "productPrice": 600

If the server detects a conflict because the ETag in the request does not match the current ETag value of the resource, the server responds with a ‘412 Precondition Failed‘ status code, indicating that the resource has been modified by another user:

HTTP/1.1 412 Precondition Failed
Content-Type: text/plain
ETag: "etag124"

The response body may contain additional information or instructions for the user to resolve the conflict, such as retrieving the updated product information and making further edits.

Happy Learning !!


Notify of
Inline Feedbacks
View all comments