Hinweis: Du verwendest einen veralteten Browser! Bitte aktualisiere Deinen Browser oder nutze einen der unterstützten Browser. Weitere Informationen
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-tokenNOTE: 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>