{"id":92,"date":"2014-04-18T21:05:57","date_gmt":"2014-04-18T21:05:57","guid":{"rendered":"http:\/\/developer-beta.redbooth.com\/?page_id=92"},"modified":"2014-11-24T20:23:04","modified_gmt":"2014-11-24T20:23:04","slug":"api-concepts","status":"publish","type":"page","link":"https:\/\/redbooth.com\/api\/api-concepts\/","title":{"rendered":"API Concepts"},"content":{"rendered":"<p><strong>API structure<\/strong><\/p>\n<p>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).<\/p>\n<p><strong>Understanding Redbooth models<\/strong><\/p>\n<p><a href=\"https:\/\/s3.amazonaws.com\/wordpress-production\/wp-content\/uploads\/sites\/2\/2014\/04\/Screenshot-2014-04-18-15.11.23.png\"><img loading=\"lazy\" decoding=\"async\" class=\"alignnone wp-image-249 size-full\" src=\"https:\/\/s3.amazonaws.com\/wordpress-production\/wp-content\/uploads\/sites\/2\/2014\/04\/Screenshot-2014-04-18-15.11.23.png\" alt=\"\" width=\"728\" height=\"782\" srcset=\"https:\/\/wordpress-production.s3.amazonaws.com\/wp-content\/uploads\/sites\/2\/2014\/04\/Screenshot-2014-04-18-15.11.23.png 728w, https:\/\/wordpress-production.s3.amazonaws.com\/wp-content\/uploads\/sites\/2\/2014\/04\/Screenshot-2014-04-18-15.11.23-279x300.png 279w\" sizes=\"auto, (max-width: 728px) 100vw, 728px\" \/><\/a><\/p>\n<p>&nbsp;<\/p>\n<p>In Redbooth, your account is a User model. A User can belong to many Projects.<\/p>\n<p>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.<\/p>\n<p>Projects are owned by one User, and have many other Users in it. Projects contain Comments, Conversations, Task Lists, Tasks, Pages and Files.<\/p>\n<p>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.<\/p>\n<p>Similarly, Task Lists have Tasks. Task Lists provide information like start and end dates.<\/p>\n<p>Pages contain different elements: Notes (text with a title), Dividers and Files.<\/p>\n<p>Files can belong to a project independently, or they can be attached to a Comment or Page.<\/p>\n<p>Invitations are sent before you join a project, to request you to join it.<\/p>\n<p><a href=\"https:\/\/s3.amazonaws.com\/wordpress-production\/wp-content\/uploads\/sites\/2\/2014\/04\/Screenshot-2014-04-18-15.10.38.png\"><img loading=\"lazy\" decoding=\"async\" class=\"alignleft wp-image-252 size-full\" src=\"https:\/\/s3.amazonaws.com\/wordpress-production\/wp-content\/uploads\/sites\/2\/2014\/04\/Screenshot-2014-04-18-15.10.38.png\" alt=\"\" width=\"800\" height=\"490\" \/><\/a><\/p>\n<p>&nbsp;<\/p>\n<p><strong>HTTP Status Codes<\/strong><\/p>\n<p>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:<\/p>\n<ul>\n<li>200: Success. The object was found, created, updated or deleted successfully<\/li>\n<li>404: The object you&#8217;re looking for doesn&#8217;t exist.<\/li>\n<li>406: Not Acceptable (invalid format). You&#8217;re probably sending wrong JSON or you need to specify the HTTP headers.<\/li>\n<li>409: Conflict (item already exists).<\/li>\n<li>422: Unprocessable Entry.<\/li>\n<li>500: Server Error (hopefully not!). This means our server has some sort of problem.<\/li>\n<\/ul>\n<p><strong>Request headers<\/strong><\/p>\n<p>For each request, please specify the following headers:<\/p>\n<pre class=\"toolbar:2 nums:false lang:default decode:true\">Accept: application\/json<\/pre>\n<p>You can also use JSONP via application\/javascript, or by using the extension &#8220;.js&#8221; in the route.<\/p>\n<p><strong>Authentication<\/strong><\/p>\n<p>Redbooth currently uses OAuth 2 for authentication. <a href=\"http:\/\/developer-beta.redbooth.com\/authentication\/\">Refer to the Authentication section<\/a> for more details on how to generate access tokens.<\/p>\n<p><strong>General usage<\/strong><\/p>\n<p>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.<\/p>\n<p>You can also access certain project objects outside projects. In this case a list will be returned of objects from all of your projects:<\/p>\n<ul>\n<li>Task lists \u00a0 \u00a0 \u00a0 \u00a0\/task_lists<\/li>\n<li>Activities \u00a0 \u00a0 \u00a0 \u00a0\/activities<\/li>\n<\/ul>\n<p>&nbsp;<\/p>\n<p>You can also access user data shared amongst projects, such as:<\/p>\n<ul>\n<li>Users \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0\/users<\/li>\n<\/ul>\n<p><strong>Responses<\/strong><\/p>\n<p>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:<\/p>\n<p><strong>Collection of objects<\/strong><\/p>\n<pre class=\"toolbar:2 nums:false lang:js decode:true\">{\r\n\"references\": [{\r\n\"id\": \"123\",\r\n\"type: \"User\"\r\n}, ...],\r\n\"objects\": [...]\r\n}<\/pre>\n<p>For a collection of objects, the actual objects will be returned in the &#8220;objects&#8221; list, while any object referenced by the collection will be returned in the &#8220;references&#8221; list. This reduces the amount of redundant data in a request.<\/p>\n<p><strong>Pagination<\/strong><\/p>\n<p>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&#8217;t be any limit, so all the objects will be returned.<\/p>\n<p>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.<\/p>\n<p>To paginate through the entire collection, you will need to use the following parameters:<\/p>\n<ul>\n<li>since_id to get items created AFTER the specified id.<\/li>\n<li>max_id to get items created BEFORE the specified id.<\/li>\n<li>a combination of since_id and max_id to get items in a range.<\/li>\n<\/ul>\n<p><strong>Single object<\/strong><\/p>\n<pre class=\"toolbar:2 nums:false lang:js decode:true\">{\r\n\"id\": \"123\",\r\n...\r\n}<\/pre>\n<p>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 &#8220;Includes&#8221; section on a route for available includes.<\/p>\n<p><strong>Errors<\/strong><\/p>\n<pre class=\"toolbar:2 nums:false lang:js decode:true\">{\r\n\"errors\": {\"message\": \"Something went wrong\", \"type\": \"SomethingWrongError\"},\r\n...\r\n}<\/pre>\n<p>If an error occurred during a request, you will get the &#8220;errors&#8221; returned in a JSON object. In the case of POST or PUT requests, each key in &#8220;errors&#8221; corresponds to a field in the related object you are trying to create or modify.<\/p>\n<p>In all cases you will get at least two keys in &#8220;errors&#8221;, i.e.<\/p>\n<ul>\n<li>type: The type of the error<\/li>\n<li>message: Message to describe the error<\/li>\n<\/ul>\n<p>Note that there are currently only 3 error types that can be returned. They are:<\/p>\n<ul>\n<li>AuthorizationFailed: A login is required<\/li>\n<li>InsufficientPermissions: You do not have the necessary permissions to perform this action<\/li>\n<li>InvalidRecord: One of more fields in your object are invalid<\/li>\n<li>ObjectNotFound: One or more specified objects were not found<\/li>\n<\/ul>\n<p>In all cases you will also get an equivalent HTTP Status code returned.<\/p>\n<p><strong>JSONP requests<\/strong><\/p>\n<p>For JSONP requests (using the &#8220;js&#8221; format), the response will be javascript of the following format:<\/p>\n<pre class=\"toolbar:2 nums:false lang:js decode:true\">callback({DATA})<\/pre>\n<p>Where &#8220;callback&#8221; is a javascript function specified by the callback parameter, and &#8220;DATA&#8221; is the normal data returned by the request.<\/p>\n<p><strong>A note about RESTful routes<\/strong><\/p>\n<p>Unless otherwise stated, most objects on the API conform to the following routes:<\/p>\n<ul>\n<li>GET \/collection to list objects<\/li>\n<li>GET \/collection\/id to show an object<\/li>\n<li>POST \/collection to create objects<\/li>\n<li>PUT \/collection\/id to update an object<\/li>\n<li>DELETE \/collection\/id to delete an object<\/li>\n<\/ul>\n<p>All API methods accept JSON as input, and will return either JSON or JSONP if specified.<\/p>\n<p>XML and YAML might be present on some parts, but are not officially supported.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>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 &nbsp; &hellip; <a href=\"https:\/\/redbooth.com\/api\/api-concepts\/\">Continued<\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"parent":0,"menu_order":0,"comment_status":"open","ping_status":"open","template":"template-redbooth-pages.php","meta":{"footnotes":""},"class_list":["post-92","page","type-page","status-publish","hentry"],"_links":{"self":[{"href":"https:\/\/redbooth.com\/api\/wp-json\/wp\/v2\/pages\/92","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/redbooth.com\/api\/wp-json\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/redbooth.com\/api\/wp-json\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/redbooth.com\/api\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/redbooth.com\/api\/wp-json\/wp\/v2\/comments?post=92"}],"version-history":[{"count":0,"href":"https:\/\/redbooth.com\/api\/wp-json\/wp\/v2\/pages\/92\/revisions"}],"wp:attachment":[{"href":"https:\/\/redbooth.com\/api\/wp-json\/wp\/v2\/media?parent=92"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}