Common

Secured Resources

Clients making calls to the API on behalf of a user require a bearer access token which can be acquired via a simple authorization flow.

GET /api/v1/(resource)
Request Headers:
 
Status Codes:
  • 401 Unauthorized – Invalid or no Authorization request header provided.
  • 403 Forbidden – The authorization was not granted by an active user.

Example:

GET /api/v1/(resource) HTTP/1.1
Authorization: Bearer 8wB8QtpULBVNuL2mqBaWdIRWX30qKtIK3E5QbOWP
POST /api/v1/(resource)
Request Headers:
 
Status Codes:
  • 401 Unauthorized – Invalid or no Authorization request header provided.
  • 403 Forbidden – The authorization was not granted by an active user.

Example:

POST /api/v1/(resource) HTTP/1.1
Authorization: Bearer 8wB8QtpULBVNuL2mqBaWdIRWX30qKtIK3E5QbOWP

Status Codes

  • 200 OK

    The body will be a JSON object whose contents are resource specific:

    {
      "key1": value1,
      "key2": value2,
      ...
    }
    
  • 201 Created

    The body will be a JSON object whose contents are resource specific:

    {
      "key1": value1,
      "key2": value2,
      ...
    }
    
  • 400 Bad Request

    The body will be a JSON object of the form:

    {
      "errors": "This was a bad request because..."
    }
    

    The errors string is resource and error specific.

  • 403 Forbidden – The body will be empty.

  • 404 Not Found – The body will be empty.

  • 405 Method Not Allowed – The body will be empty.

  • 500 Internal Server Error

    The body will be a JSON object of the form:

    {
      "errors": "This request failed because..."
    }
    

    The errors string is resource and error specific.

Request Parameters

Resources that accept request parameters expect them in the request body using the application/x-www-form-urlencoded or application/json formats with a character encoding of UTF-8.

Timestamps

Unless otherwise specified, all timestamps are of the form %Y-%m-%d %H:%M:%S %Z-%z (see Python strftime formatting) and returned as UTC unless otherwise noted.

Example timestamp:

"2013-04-14 19:55:22 UTC-0000"

List Resources

Some resources return a list of results that can span requests. These resources all take a common set of query parameters and return a common set of response data to help iterate through large lists of data.

GET /api/v1/(list_resource)
Query Parameters:
 
  • size – The number of results to return per call (Default: 10. Maximum: 50).
  • cursor – The cursor string signifying where to start the results.
Status Codes:
  • 200 OK

    Successfully called the list_resource.

    Response Data:
    • cursor – If more results are available, this root level response value will be the next cursor string to be passed back into this resource to grab the next set of results. If no more results are available, this field will be absent.

Example first request:

GET /api/v1/(list_resource)?size=5 HTTP/1.1

Example first response:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "results": ["result1", "result2", "result3", "result4", "result5"],
  "cursor": "hsajkhasjkdy8y3h3h8fhih38djhdjdj"
}

Example second request:

GET /api/v1/(list_resource)?size=5&cursor=hsajkhasjkdy8y3h3h8fhih38djhdjdj HTTP/1.1

Example second response:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "results": ["result6", "result7", "result8"]
}