HTTP Status Code 201, also known as "201 Created", means the request was successful and a new resource was created as a result. This response status is part of the 2xx (Success) class of HTTP codes.
HTTP 201 Created Status Code: Meaning, Use Cases, and Best Practices
HTTP Status Code 201, also known as "201 Created", means the request was successful and a new resource was created as a result. This response status is part of the 2xx (Success) class of HTTP codes.
It is commonly used in RESTful APIs when a POST request leads to the creation of a new entity. The server typically returns a Location header pointing to the newly created resource.
According to the HTTP/1.1 specification, "The newly created resource can be referenced by the URI(s) returned in the response, with the most specific URI given by a Location header field."
When to Use HTTP 201 (Use Cases)
The 201 Created response is primarily used in situations where a new resource is generated as a result of the request. Below are some common use cases:
APIs & Web Services
When a client submits a POST request to create a new user, order, or record in a database.
- Example: Registering a new user in an authentication system.
- If a PUT request creates a resource at a known URL that didn’t exist before, it may also return 201 Created.
File Uploads
When a user uploads a file to a cloud storage service, and the server creates a new reference for the uploaded file.
- Example: Uploading a profile picture to a user’s account.
Social Media & Content Posting
When a user creates a new post, comment, or article, and the system generates a unique identifier for the content.
- Example: Publishing a blog post via an API.
HTTP 201 Example
Here’s a simple example of how a POST request might return a 201 Created status code:
Request:
POST /users HTTP/1.1
Host: api.example.com
Content-Type: application/json
{
"name": "John Doe",
"email": "johndoe@example.com"
}
Response:
HTTP/1.1 201 Created
Location: https://api.example.com/users/123
Content-Type: application/json
{
"id": 123,
"name": "John Doe",
"email": "johndoe@example.com"
}
The Location header provides the URL of the newly created resource. Best practices suggest including a representation of the created resource in the response body, though it is not strictly required.
201 vs. 200 vs. 204 – What’s the Difference?
Understanding when to use 201 Created versus other similar status codes is crucial for API design.
Related Status Codes
- 200 OK – Used for successful GET, PUT, and sometimes POST requests when returning data.
- 202 Accepted – Used when a request has been received but not yet acted upon.
- 204 No Content – Used when a request is successful but does not return a response body.
201 vs. 202 vs. 204 – What’s the Difference?
- 201 Created: Indicates immediate resource creation.
- 202 Accepted: The request has been received but processing is still in progress.
- 204 No Content: The operation was successful, but there is no response body.
Let’s check the versus!
- 201 vs. 202 Accepted: 201 Created indicates immediate resource creation, while 202 Accepted means the request has been received but processing is still in progress.
- 201 vs. 204 No Content: 201 Created implies a new resource exists and often includes a response body or a Location header, whereas 204 No Content means the operation was successful but has no response body.
Frequently Asked Questions about HTTP 201 Created
Should I return a body with HTTP 201 Created?
- While the HTTP specification doesn’t require a response body, it is often useful to return details of the newly created resource, such as an ID or relevant metadata.
Can 201 be used with PUT?
- 201 Created is typically used with POST, but in some cases, a PUT request may return 201 if it results in the creation of a new resource.
What is the difference between 201 and 202 Accepted?
- 201 Created: Confirms that the resource was immediately created.
- 202 Accepted: Confirms that the request was received, but the resource is still being processed.
Visual Guide: HTTP 201 Created Workflow
To better understand how 201 Created works in a typical API workflow, consider the following diagram:
Conclusion
Understanding HTTP 201 Created is essential for designing effective APIs that provide clear and predictable responses when new resources are created. By following best practices—such as including a Location header and returning relevant details—you can ensure a smooth user experience and efficient API interactions.
Need Better API Management? Try AbstractAPI!
If you're looking for tools to streamline your API development and improve response handling, check out AbstractAPI. Our suite of API services simplifies implementation, enhances data validation, and optimizes API performance.
Get started today and build more reliable applications!
