Response status codes

Success

Successes differ from errors in that their body may not be a simple response object with a code and a message. The headers however are consistent across all calls:

  • GET, PUT, DELETE returns 200 OK on success,
  • POST returns 201 on success,

When retrieving stuff for example:

Status: 200 OK { { id: thing_1, name: 'My first thing' }, { id: thing_2, name: 'My second thing' } }

Error

Error responses are simply returning standard HTTP error codes along with some additional information:

  • The error code is sent back as a status header,
  • The body includes an object describing both the code and message (for debugging and/or display purposes),

For a call with an invalid authentication token for example:

Status: 401 Access denied { code: 401, message: 'Access denied: invalid authentication token.' }

Authenticate

This method allows users to retrieve stuff.

Response

Sends back a collection of things.

Authentication: bearer TOKEN { id: thing_2, name: 'My second thing' }

For errors responses, see the response status codes documentation.

GET _posts/2012-12-27-get-stuff.md Get stuff

This method allows users to retrieve stuff.

Request

  • The headers must include a valid authentication token.

Response

Sends back a collection of things.

Status: 200 OK { { id: thing_1, name: 'My first thing' }, { id: thing_2, name: 'My second thing' } }

For errors responses, see the response status codes documentation.

POST _posts/2012-12-26-post-a-thing.md Post a thing

This method allows users to create a new thing.

Request

  • The headers must include a valid authentication token.
  • The body can’t be empty and must include at least the name attribute, a string that will be used as the name of the thing.

Authentication: bearer TOKEN { name: 'My new thing' }

Response

If succeeds, returns the created thing.

Status: 201 Created { id: new_thing, name: 'My new thing' }

For errors responses, see the response status codes documentation.

PUT _posts/2012-12-25-put-a-thing.md Update a thing

This method allows the user to retrieve his stuff.

Request

  • :id is the id the thing to update.
  • The headers must include a valid authentication token.
  • The body can’t be empty and must include at least the name attribute, a string that will be used as the name of the thing.

Authentication: bearer f862f658-ad89-4fcb-995b-7a4c50554ff6 { name: 'My new thing' }

Response

Sends back a collection of things.

Status: 200 OK { { id: thing_1, name: 'My first thing' }, { id: thing_2, name: 'My second thing' } }

For errors responses, see the response status codes documentation.

DELETE _posts/2012-12-24-delete-a-thing.md Delete a thing

This method allows the user to post a new thing to his stuff.

Request

  • :id is the id the thing to delete.
  • The headers must include a valid authentication token.
  • The body is omitted.

Response

Sends back a collection of things.

Status: 200 Deleted { code: 200, message: 'Your thing (id: 736) was deleted' }

For errors responses, see the response status codes documentation.