201 Status Code - Created

What is HTTP Status Code 201?

The HTTP Status Code 201 is synonymous with success, specifically indicating that a new resource has been successfully created in response to the client's request. This status code is part of the 2xx series of HTTP status codes that confirm that a client's request was successfully received, understood, and accepted. The 201 Created status code is usually returned after a POST request, or sometimes a PUT request if the action resulted in the creation of a new resource.

Understanding 201 Status Code

• Resource Creation: The crux of the 201 Created status code is the successful creation of a new resource on the server. This is typically in response to a POST request where the client submits data to be stored as a new resource.

HTTP/1.1 201 Created

• Location Header: A significant aspect of the 201 Created status code is that the response should include a Location header indicating the URI of the newly created resource.

HTTP/1.1 201 Created
Location: /api/users/123

Why 201 Created?

The 201 Created status code provides clear feedback to the client that a new resource has been created successfully. It's a crucial part of RESTful API design, ensuring accurate communication between the client and server.

Benefits of 201 Created

• Explicit Success Confirmation: Unlike a generic success code, 201 Created explicitly confirms the creation of a new resource, providing clearer communication.

• Resource Location: The Location header provides the client with the URI where the new resource can be found, which is useful for future interactions with that resource.

How does 201 Created Work?

1. Client Sends a Request:

   The client initiates a POST request to the server, submitting data for a new resource.

POST /api/users HTTP/1.1
Host: www.example.com
Content-Type: application/json

{
  "name": "John Doe"
}

2. Server Processes the Request:

   The server processes the request, creating a new user resource with the submitted data.

3. Server Sends a Response:

The server sends a 201 Created response to the client, including a Location header pointing to the URI of the newly created resource.

HTTP/1.1 201 Created
Location: /api/users/123

Components of a 201 Created Response

A 201 Created response contains several components:

• Status Line: The first line of the response, indicating the 201 Created status code.

HTTP/1.1 201 Created

• Headers: Headers like Location provide additional information about the response. The Location header is particularly important as it gives the client the URI of the newly created resource.

• Message Body: While optional, the message body can contain a representation of the newly created resource, providing the client with the initial state and details of that resource.

{
  "id": 123,
  "name": "John Doe"
}

Examples of 201 Code HTTP Created

Creating a New Resource:

POST /api/users HTTP/1.1
Host: www.example.com
Content-Type: application/json

{
  "name": "John Doe"
}

Response:

HTTP/1.1 201 Created
Location: /api/users/123

{
  "id": 123,
  "name": "John Doe"
}

In this example, a new user resource is created on the server in response to a POST request from the client. The 201 Created status code, along with the Location header, informs the client about the successful creation and the location of the new resource.

Conclusion

The 201 Created status code is a fundamental aspect of RESTful API design, providing explicit confirmation of the successful creation of a new resource. Understanding the 201 Created status code is essential for developers to accurately interpret server responses and ensure the proper functioning of their applications.

Learn about other codes in 2xx family of HTTP status codes such as 200 Status Code and 204 Status Code.