201 Created

201 Created, just like 200 OK, means that the request was successful, but it also resulted in a new resource being created.

In the case of a PUT request, it means that a new resource was created on the actual url that was specified in the request.


PUT /new-resource HTTP/1.1
Content-Type: text/html

HTTP/1.1 201 Created
ETag: "foo-bar"

POST requests

If you got a 201 in response to a POST request, it means that a new resource was created at a different endpoint. For those cases, a Location header must be included to indicate where the new resource lives.

In the following example, we’re creating a new resource via POST, and the server responds with the new location and the ETag of the new resource.

POST /collection/add-member HTTP/1.1
Content-Type: application/json

{ "foo": "bar" }
HTTP/1.1 201 Created
ETag: "gir-zim"
Location: /collection/546

It’s common misconception that POST is generally for creating new resources, and PUT is strictly for updating them. However, the real difference is that PUT should be the preferred method if the client can determine the url of the resource it wants to create.

In practice most servers do want control over the url, perhaps because it’s tied to an auto-incrementing database id.

HTTP series

This article is part of a series about the HTTP protocol. Read them all here:

Informational 1xx

Successful 2xx

Redirection 3xx

Client Error 4xx

Server Error 5xx

Web mentions