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: - 200 OK – no error
- 404 Not Found – the “magazines” resource does not exist
-
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: - 201 Created – magazine created
- 405 Method Not Allowed – unable to create “magazine” resource
-
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"
}