# Basics

Coursebase's API is a collection of HTTP RPC-style methods.

• Method URLs are in the form of https://customdomain.com/api/{method}
• Use HTTPS with TLS version 1.2 or greater
• Send all requests as a HTTP POST
• Set the Content-type HTTP header to application/json and pass all arguments as JSON with the exception of requesting an authentication token
• Transmit your token as a bearer token in the Authorization HTTP header. Note that the token has the string Bearer prepended to it, indicating the OAuth 2.0 authentication scheme

Example request:

POST /api/example.method
Content-type: application/json
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

{"example":"request"}

All responses will be a JSON object which will always contain a top level status property. This property will be success or error. For error statuses, there will also be an error property with a machine readable error code. For success statuses, there will also be a data property. The shape of this data property is defined in the documentation for each method.

{
  "status": "success",
  "data": {
    "property": "value"
  }
}

{
  "status": "error",
  "error": "not_found"
}

# Pagination

If a method's description states that it returns paginated results, this means that it will return an array of data with a maximum number of results and a cursor — a property called next in the data part of the response — to the next set of results. By default all paginated responses return 100 results.

All methods that use pagination behave according to the following:

• next is optional in the request. If the request doesn't include a next property in its body, this means the first page will be returned.
• next is optional in the response. If the response returns null as the value for next, this means that there are no more pages to be fetched.
• In order to fetch the next page, a new request with exactly the same parameters must be sent, with the addition of the next cursor received in the previous response. If the parameters are changed there is no guarantee that the search will contain accurate results.
• The last page can have less results than the maximum number of results per page.
• The first page can be the last page.
• It is possible under certain conditions that the last page will return an empty array.
• Cursors are short-lived, they shouldn't be stored and reused.

# Examples

# Request to fetch the first page

{
  "search": "some search terms"
}

# Response with a cursor to the next page

{
  "status": "success",
  "data": {
    "results": ["some", "results"],
    "next": "RGVRt1m9DRWp"
  }
}

# Request with cursor

{
  "search": "some search terms",
  "next": "RGVRt1m9DRWp"
}

# Response with the last page

{
  "status": "success",
  "data": {
    "results": ["last", "page"],
    "next": null
  }
}

# Response with empty results

{
  "status": "success",
  "data": {
    "results": [],
    "next": null
  }
}

Each method will describe what parameters it accepts and what data it returns in its documentation.

# Rate limits

All methods rely on rate limits to help provide a good experience for all users. All rate limits are per client ID. By default, each client is limited to 100 requests per 10-second period.

If you exceed a rate limit, a 429 Too Many Requests will be returned with a Retry-After HTTP header containing the number of seconds until you can retry. By evaluating the Retry-After header you can wait for the indicated number of seconds before retrying the same request. The following response will also be returned:

{
  "status": "error",
  "error": "rate_limit_exceeded"
}

# Payload limits

All methods have a limit to the length of the request's body. If any payload exceeds 100KB, a 400 Bad Request will be returned, along with the following response:

{
  "status": "error",
  "error": "payload_limit_exceeded"
}

# Common errors

Each method's documentation lists its specific errors if applicable. These are the common errors that are possible for each method:

# Authentication errors

Error responses related to authentication follow the OAuth 2.0 specification as described at https://tools.ietf.org/html/rfc6750#section-3.1