API structure

Every part of Redbooth can be accessed by the API with simple requests. Usual actions include listing objects, adding a new one, editing, showing one and destroying a record (index, new, edit, show, delete).

Understanding Redbooth models

 

In Redbooth, your account is a User model. A User can belong to many Projects.

The membership of a User in a Project is represented by a Person model. Person stores information like the role and the date when User joined the Project.

Projects are owned by one User, and have many other Users in it. Projects contain Comments, Conversations, Task Lists, Tasks, Pages and Files.

Comments are the most important concept in Redbooth. A Comment belongs to a Conversation or a Task, allowing them to be threaded. Comments store important information, like the number of hours you spent on a Task or status changes for it.

Similarly, Task Lists have Tasks. Task Lists provide information like start and end dates.

Pages contain different elements: Notes (text with a title), Dividers and Files.

Files can belong to a project independently, or they can be attached to a Comment or Page.

Invitations are sent before you join a project, to request you to join it.

 

HTTP Status Codes

For each request you make to the Redbooth API, we will return an HTTP status code. Following convention, the following status codes will be returned for each request:

  • 200: Success. The object was found, created, updated or deleted successfully
  • 404: The object you’re looking for doesn’t exist.
  • 406: Not Acceptable (invalid format). You’re probably sending wrong JSON or you need to specify the HTTP headers.
  • 409: Conflict (item already exists).
  • 422: Unprocessable Entry.
  • 500: Server Error (hopefully not!). This means our server has some sort of problem.

Request headers

For each request, please specify the following headers:

You can also use JSONP via application/javascript, or by using the extension “.js” in the route.

Authentication

Redbooth currently uses OAuth 2 for authentication. Refer to the Authentication section for more details on how to generate access tokens.

General usage

The following project objects have APIs: Projects, Activities, Users, Comments, Conversations, Task Lists, Tasks, Pages, Invitations and Files. You can access them through RESTful interfaces, described below.

You can also access certain project objects outside projects. In this case a list will be returned of objects from all of your projects:

  • Task lists        /task_lists
  • Activities        /activities

 

You can also access user data shared amongst projects, such as:

  • Users            /users

Responses

There are two possible types of response in the API, depending on whether you are retrieving a collection of objects or just a single object:

Collection of objects

For a collection of objects, the actual objects will be returned in the “objects” list, while any object referenced by the collection will be returned in the “references” list. This reduces the amount of redundant data in a request.

Pagination

The number of returned objects is by default limited to 20. This limit can be changed by providing a count parameter. If the value of count is 0 there won’t be any limit, so all the objects will be returned.

There is one exception to this rule, which is the activities index action (/api/1/activites or /api/1/projects/:project_id/activites), where the limit cannot be changed to more than 20.

To paginate through the entire collection, you will need to use the following parameters:

  • since_id to get items created AFTER the specified id.
  • max_id to get items created BEFORE the specified id.
  • a combination of since_id and max_id to get items in a range.

Single object

For a single object, you will get a single JSON object containing the properties of the said object. In addition if you pass in one or more include[] parameters, additional referenced elements will be returned in the object, e.g. comments. Refer to the “Includes” section on a route for available includes.

Errors

If an error occurred during a request, you will get the “errors” returned in a JSON object. In the case of POST or PUT requests, each key in “errors” corresponds to a field in the related object you are trying to create or modify.

In all cases you will get at least two keys in “errors”, i.e.

  • type: The type of the error
  • message: Message to describe the error

Note that there are currently only 3 error types that can be returned. They are:

  • AuthorizationFailed: A login is required
  • InsufficientPermissions: You do not have the necessary permissions to perform this action
  • InvalidRecord: One of more fields in your object are invalid
  • ObjectNotFound: One or more specified objects were not found

In all cases you will also get an equivalent HTTP Status code returned.

JSONP requests

For JSONP requests (using the “js” format), the response will be javascript of the following format:

Where “callback” is a javascript function specified by the callback parameter, and “DATA” is the normal data returned by the request.

A note about RESTful routes

Unless otherwise stated, most objects on the API conform to the following routes:

  • GET /collection to list objects
  • GET /collection/id to show an object
  • POST /collection to create objects
  • PUT /collection/id to update an object
  • DELETE /collection/id to delete an object

All API methods accept JSON as input, and will return either JSON or JSONP if specified.

XML and YAML might be present on some parts, but are not officially supported.