8 Falsehoods Rails developers believe about REST

4. Every successful POST request should respond with a 201

A common misconception is that POST requests are only to be used to create a new resource (or a new database record), and so should always return status 201 on a successful request to indicate that the resource was created successfully.

5. Always return 201 when a request creates a new database record

The HTTP 201 status code is used to indicate that a new resource has been made available by the application. Sometimes resources represent a database record, but sometimes they do not. Sometimes DB records are created, but a new resource is not.

A good heursitc to decide if you should return 201 or 200, is to ask: Has a new URL been made available by this request (e.g. POST /users.json => creates => Location: /users/1.json).

7. PATCH and PUT are synonymous

Rails made the transition from using PUT as the default verb when updating a record, to using PATCH in Rails 3.

This seamless transition gave the impression that these two verbs are interchangable.

But there are semantic differences to these two verbs. Namely that

PATCH

Request contains a partial representation of the state to change on a user

Example:

{ "user": { "email": "[email protected]" } }

POST

Request contains a full representation of the state to change on a user

Example:

  { 
    "user": {
      "id": 1, 
      "email": "[email protected]",
      "full_name": "Gavin Morrice",
      // ...
    } 
  }