Use HTTP methods and status codes

Meaningful status codes helps consumers utilise your API.

Should

HTTP methods and status codes should be used in compliance with their definitions under the HTTP/1.1 standard.

The action taken on the representation will be contextual to the media type being worked on and its current state.

Examples

GET /magazines

List all magazines contained within the /magazines resource

GET /magazines HTTP/1.1
Host: example.gov.au
Accept: application/json, text/javascript

A response of “200 OK” indicating that the request has succeeded.

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{...}
Status Codes:
POST /magazines

Create new magazine within the /magazines resource

POST /magazines HTTP/1.1
Host: example.gov.au
Accept: application/json, text/javascript

{...}

A response of “201 Created” indicates that the request has been fulfilled.

The URI of the new resource is provided in the response

HTTP/1.1 201 Created
Vary: Accept
Content-Type: text/javascript

{ "id": "1234" }

However, no effect if the resource already exists.

HTTP/1.1 405 Method Not Allowed
Vary: Accept
Content-Type: text/javascript

{
  "developerMessage" : "Unable to create a magazine with ID of 1234 because a magazine with that ID already exists",
  "userMessage" : "Unable to create duplicate magazine 1234",
  "errorCode" : "444444",
  "moreInfo" : "http://api.example.gov/v1/documentation/errors/444444.html"
}
Status Codes:
PUT /magazines

Replace all magazines in the /magazines resource with those in the request

PUT /magazines HTTP/1.1
Host: example.gov.au
Accept: application/json, text/javascript

[ ... ]

200 indicates that the request has succeeded.

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{ "id": "1234" }
Status Codes:
  • 200 OK – magazines replaced
PUT /magazines/1234

Replace the /magazines/1234 resource with the representation in the request

PUT /magazines/1234 HTTP/1.1
Host: example.gov.au
Accept: application/json, text/javascript

[ ... ]

200 indicates that the request has succeeded.

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{ "id": "1234" }
Status Codes:
  • 200 OK – magazine 1234 replaced
DELETE /magazines

Delete all magazines from the /magazines resource

DELETE /magazines HTTP/1.1
Host: example.gov.au
Accept: application/json, text/javascript

200 indicates that the request has succeeded.

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{ "id": "1234" }
Status Codes:
  • 200 OK – all magazines deleted
DELETE /magazines/1234

Delete the magazine resource /magazines/1234

DELETE /magazines/1234 HTTP/1.1
Host: example.gov.au
Accept: application/json, text/javascript

200 indicates that the request has succeeded.

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript
Status Codes:
  • 200 OK – magazine 1234 deleted
HEAD /magazines

List metadata about the /magazines resource, such as last-modified-date.

HEAD /magazines HTTP/1.1
Host: example.gov.au
Accept: application/json, text/javascript

200 indicates that the request has succeeded.

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{...}
Status Codes:
  • 200 OK – magazines metadata found
HEAD /magazines/1234

List metadata about /magazines/1234, such as last-modified-date.

HEAD /magazines HTTP/1.1
Host: example.gov.au
Accept: application/json, text/javascript

200 indicates that the request has succeeded.

HTTP/1.1 200 OK
Vary: Accept
Content-Type: text/javascript

{...}
Status Codes:
  • 200 OK – metadata about magazine 1234 found

HTTP response principles

No values in keys – for example, {“125”: “Environment”} is bad, {“id”: “125”, “name”: “Environment”} is good. Note that in the first (bad) example, the key is “125” and the value is “Environment”. This is a problem because the key is supposed to be the name of the value. In the second example (good) the keys are descriptions of their coresponding values.

No internal-specific names (for example, “node” and “taxonomy term”)

Metadata should only contain direct properties of the response set, not properties of the members of the response set

Provide error responses

Error responses should be as descriptive and specific as possible. They should also include a message for the end-user (when appropriate), internal error code (corresponding to some specific internally determined ID) and links where developers can find more information. For example:

{
  "developerMessage" : "Verbose, plain language description of the problem.
             Provide developers suggestions about how to solve their problems here",
  "userMessage" : "This is a message that can be passed along to end-users, if needed.",
  "errorCode" : "444444",
  "moreInfo" : "http://api.example.gov/v1/documentation/errors/444444.html"
}