Responses

Content type

Make sure the following headers are set correctly in order to return a JSON response.

• Set Content-Type header to application/json

• Set Accept header to application/json

Successful response

Successful API queries will return a 200 HTTP Response code.

The reesponse body will be in the following format, there will always be data and meta fields and for list of items there will be a pagination field:

{
  "data": {
    // data 
  },
  "meta": {
    // any meta data we need to send eg rate limits etc
  },

  // Optional (included if the data contains a list of items)
  "pagination": {
    // pagination data
  },
}

For single object (eg an Announcement) data will be an object:

{
  "data": {
    "idx": "announcement_abcd123",
    "name": "My first announcement",
    "slug": "my-first-announcement",
    // .. etc
  },
  "meta": {
    // any meta data we need to send eg rate limits etc
  }
}

For multiple objects (eg a list of Announcements) data will be an array of objects:

{
  "data": [
    {
      "idx": "announcement_abcd123",
      "name": "My first announcement",
      "slug": "my-first-announcement",
     // .. etc
    },
    {
      "idx": "announcement_abcd098",
      "name": "My second announcement",
      "slug": "my-second-announcement",
     // .. etc
    }
  ],
  "pagination": {
    "total": 100,
    // any pagination data we need to send
  }
  "meta": {
    // any meta data we need to send eg rate limits etc
  }
}

Error response

As much as possible, Frill attempts to use appropriate HTTP status codes to indicate the general class of problem, and this status code is repeated in the code section of the meta response.

400 (Bad Request) Any case where a parameter is invalid, or a required parameter is missing. This includes the case where no OAuth token is provided and the case where a resource ID is specified incorrectly in a path.

403 (Forbidden) The requested information cannot be viewed by the acting user, for example, because they are not friends with the user whose data they are trying to read.

404 (Not Found) Endpoint does not exist.

405 (Method Not Allowed) Attempting to use POST with a GET-only endpoint, or vice-versa.

422 (Unprocessable Entity) The request could not be completed as it is. Use the information included in the response to modify the request and retry.

500 (Internal Server Error) Frill's servers are unhappy. The request is probably valid but needs to be retried later. If the problem persist please contact [e-mail]

Error responses will return JSON a message in the following format.

{
  "error": true,
  "message": "Please provide a status_id"
}