1. Timothy Corbett-Clark
  2. rest-api-blueprint

Wiki

Clone wiki

rest-api-blueprint / StatusCodes

In deciding which HTTP status codes to return, be comprehensive but not pointlessly so. The minimum set of supported codes should be:

  • 200 - OK
  • 201 - Created
  • 304 - Not Modified
  • 400 - Bad Request
  • 401 - Unauthorized
  • 403 - Forbidden
  • 404 - Not Found
  • 500 - Internal Server Error

The status codes should be explained in the on-line docs, and describe both standard generic meaning together with the refined meaning for that context.

The returned response should include lots of information and ideally link to on-line docs.

The code includes a utility use_pretty_default_error_handlers to help complete the information required for each code, and ensure that the correct output is used depending upon the Accept header.

So for example:

~/code/rest-api-blueprint$ http http://127.0.0.1:5000/does-not-exist -j -v
GET /does-not-exist HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate, compress
Host: 127.0.0.1:5000
User-Agent: HTTPie/0.3.0



HTTP/1.0 404 NOT FOUND
Content-Length: 163
Content-Type: application/json
Date: Tue, 06 Nov 2012 15:20:13 GMT
Server: Werkzeug/0.8.3 Python/2.7.3

{
    "message": "", 
    "status": "error", 
    "status_code": 404, 
    "status_long_message": "Nothing matches the given URI", 
    "status_short_message": "Not Found"
}

But without the "-j" option (and hence not specifically asking for media application/json):

tcorbettclark@domestic:~/code/rest-api-blueprint$ http http://127.0.0.1:5000/does-not-exist -v | head -30
GET /does-not-exist HTTP/1.1
Host: 127.0.0.1:5000
Accept-Encoding: gzip, deflate, compress
Accept: */*
User-Agent: HTTPie/0.3.0



HTTP/1.0 404 NOT FOUND
Content-Type: text/html; charset=utf-8
Content-Length: 2051
Server: Werkzeug/0.8.3 Python/2.7.3
Date: Tue, 06 Nov 2012 15:21:49 GMT

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8">
        <title>404 - Not Found</title>
        <style>
            ::-moz-selection {
                background: #b3d4fc;
                text-shadow: none;
            }

            ::selection {
                background: #b3d4fc;
                text-shadow: none;
            }

See:

Updated