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.

Example

PUT /new-resource HTTP/1.1
Content-Type: text/html
Host: example.org

...

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
Host: example.org

{ "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.