HTTP Responses

All of the responses generated by the API are done in a standardized format for success and error messages. In addition to the responses themselves, the status codes are done in a similar standard way as well. The API documentation can be found here on GitHub pages.

Response Format

As stated above, the responses are generated in a standard format. The response will always be JSON and will always contain the key status. There are two types of responses: error and success.

Success

There are two types of success message: a generic success and a success with some data. A generic success response only has the key status with the value success. This is for responses that do not require any extra data to be given to the client. These are the creation, modification, and deletion routes. A success with data response has the keys status and data. Just like the generic success response, the status key will always be success, and the data key will always be a map with some other fields. This primarily for the description or listing of a resource, as well as logging in a user.

Error

Every error message contains two fields: status and reason. The status field will always be error as it is an error response and the reason field will have the reason that the request failed. Accompanied with the reason field is the status code which will reflect a general reason for why the request failed.

Examples

Generic Response:

{
  "status": "success"
}

Success with Data Response:

{
  "status": "success",
  "data": {
    "some": "data",
    "a_number": 2,
    "array": ["element 1", "element 2"],
    "object": {
      "key": 1
    }
  }
}

Error:

{
  "status": "error",
  "reason": "some reason"
}

Status Codes

There are five “classes” of status codes that are used:

• Informational
  • signify how the processing is going
  • range from 100 to 103
• Successful
  • signify a request was completed successfully
  • range from 200 to 208, and 226
• Redirects
  • signify that the client must go somewhere else to request the resource
  • range from 300 to 308
• Client Errors
  • signify that the client messed up in the request
  • range from 400 to 418, and from 421 to 431, and 451
• Server Errors
  • signify that the server messed up in processing of the request
  • range from 500 to 511

We only use successful, client error, and server error status codes. The most common ones that are used are 101 (Switching Protocols), 200 (Ok), 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 405 (Method Not Allowed), 409 (Conflict), and 500 (Internal Server Error). Ideally, the 500 status code will happen as infrequently as possible as they signify something greater that is wrong.

To see a full list of the status codes, see the MDN page. For more entertaining representations of status codes, see a slide from this presentation (NOTE: there is explicit language, so view at your own discretion), HTTP Cats, and HTTP Status Dogs.