Resources

General Note (/api)

All resources are available through route /api, which means that for unnecessary redundancy it is being ommited. The examples, though, will contain the full path including /api.

Resources structure

There are several types of resources that can be requested through the API.

This is the basic structure and hierarchy of the relocators:

projects
projects -> folders
projects -> folders -> items
projects -> folders -> items -> upload
projects -> folders -> items -> metadata

with items being one of the following item_types: ['SharedFile', 'Playlist', 'Gallery']

and only for clips in a playlist as a special resource:

projects -> clips
projects -> clips -> upload
projects -> clips -> metadata

Common Requests

This section describes common request methods that work on a variety of resources. As an example, we use the "projects" resource.

Listing resources

A listing returns a JSON Array of entities.

Request

GET /api/projects HTTP/1.1
Authorization: Bearer example-token

Response

HTTP/1.1 200 OK
Content-Type: application/json

[{"id":1,"name":"First project"},{"id":2,"name":"Second project"}]

Requesting Details on a Resource

In some cases more detailed information on a specific resource may be obtained.

Request

GET /api/projects/1 HTTP/1.1
Authorization: Bearer example-token
NOTE: in the resource description below, the URI of this request would be desribed as /projects/{id}, meaning that the {id} part is to be replaced with the 'id' attribute of a project ('1' in this case), as returned by the resource listing.

Response

HTTP/1.1 200 OK
Content-Type: application/json

{"id":1,"name":"First project","something":"else"}

Creating a resource

Resources can be created by sending a POST request with the new resources' attributes. The resource body including any implicitly set attributes (such as the id ) will be returned as the response body.

Request

POST /api/projects/1/folders HTTP/1.1
Authorization: Bearer example-token

{"folder":{"name":"Folder name"}}

Response

HTTP/1.1 201 Created
Location: http://example.com/api/projects/1/folders/1

{"id":123,"name":"Folder name"}

Updating a resource

Resources can be updated by sending a PUT request with the attributes that should be changed.

Request

PUT /api/projects/1/folders/1 HTTP/1.1
Authorization: Bearer example-token

{"folder":{"name":"Another name"}}

Response

HTTP/1.1 204 No Content

Deleting a Resource

When you want to delete a resource, send a DELETE request to the resource's detail URI.

Request

DELETE /api/projects/1/folders/1 HTTP/1.1
Authorization: Bearer example-token

Response

HTTP/1.1 204 No Content

Resource nesting

As mentioned above, most resources are nested in a hierarchical structure. For example the "folders" resource is nested under the "projects" resource.
Resource nesting is also reflected in the URI structure. For example "/projects/123/folders/234" represents the URI for a folder with the identifier '234', which is associated with the project identified by '123'.

Content negotiation

All resource endpoints (but not the authentication endpoint) support HTTP 1.1 content negotiation mechanisms.
The following content types are supported:

  • application/json (the default)
  • application/xml

Example:

To demonstrate content negotiation, the above request and response for a list of projects could be rephrased as: 

GET /api/projects HTTP/1.1
Authorization: Bearer example-token
Accept: application/json

and:

HTTP/1.1 200 OK
Content-Type: application/json

[{"id":1,"name":"First project"},{"id":2,"name":"Second project"}]

Notes on XML formatting

Due to XML best practices on attribute naming, all underscores (ASCII 0x5F, '_') are replaced by dashes (ASCII 0x2D, '-'). So for example the "project_id" attribute of a "folders" resource would become "project-id".

Example:

This example shows the request and response for a single "projects" resource in XML. 

GET /api/projects/7 HTTP/1.1
Authorization: Bearer example-token
Accept: application/xml
HTTP/1.1 200 OK
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<project>
  <id>7</id>
  <name>Example Project</name>
  <starts-at>2013-07-17</starts-at>
  <ends-at>2055-01-01</ends-at>
</project>