Skip to content

Latest commit

 

History

History
201 lines (166 loc) · 6.14 KB

Rest-track.md

File metadata and controls

201 lines (166 loc) · 6.14 KB

Track

< Rest API documentation

The track resources are related to a video.

Base URI

http://api.annotationstool.com/v1/videos/#{videoId}/tracks

Attributes

Name Type Description Default
id * Long The track id. Generated at creation
name* String The track name. EMPTY
description String The track description. EMPTY
settings String List of track settings, not well defined at the moment. NULL
tags String String of related tags. NULL
+ logging attributes

* = required

Operations

Add a new track to a video

Add the given track to the video with id videoId. The track id must not be given . Anyway it will be overwritten.

Method Path Parameters HTTP Response
POST /videos/#{videoId}/tracks NONE 201 Created: Resource created, 400 Bad request: Request not valid, 401 Unauthorized: Operation not authorized for the user, 500 Internal server error: Error happened on the server side.

Example request

Url

POST http://api.annotationstool.com/v1/videos/123/tracks

Content

name=example+track&description=simple+track&settings={color:blue,picture=http%3A%2F%2Ficon.org%2FmyTrackIcon.png}&access=1

Response content

Location parameter in header give the URI from the new resource.

{
 id: 1,
 name: 'example track', 
 description: 'Simple track to add some basic annotations',
 settings: '{
    // Some possible settings, not well defined at the moment 
    color: \"blue\",
    picture: \"http://icon.org/myTrackIcon.png\"
 }',
 access: 1
 updated_by: 123,
 updated_at: 32421410,
 created_by: 123,
 created_at: 32421410 
}

Get a video track

Get a video track with the id trackId

Method Path Parameters HTTP Response
GET /videos/#{videoId}/tracks/#{trackId} NONE 200 Ok: Resource returned, 401 Unauthorized: Operation not authorized for the user, 404 Not found: Resource not found, 500 Internal server error: Error happened on the server side.

Example request

Url

GET http://api.annotationstool.com/videos/123/tracks/1

Content

NO CONTENT

Response content

{
 id: 1,
 name: 'example track', 
 description: 'Simple track to add some basic annotations',
 settings: '{
    // Some possible settings, not well defined at the moment 
    color: \"blue\",
    picture: \"http://icon.org/myTrackIcon.png\"
 }',
 access: 1,
 updated_by: 123,
 updated_at: 32421410,
 created_by: 123,
 created_at: 32421410 
}

Get all tracks from a video

Query tracks from a video.

Method Path Parameters HTTP Response
GET /videos/#{videoId}/tracks list queries parameters 200 Ok: Resources returned, 401 Unauthorized: Operation not authorized for the user, 404 Not found: Resource not found (#{videoId} does not exist), 500 Internal server error: Error happened on the server side.

Default sorting

By default, the tracks list should be sorted by name.

Example request

Url

GET http://api.annotationstool.com/videos/123/tracks?limit=2

Content

NO CONTENT

Response content

{
 count: 2, // Result length SPRINT 2 needed?
 offset: 0, // Offset parameter to use in case of pagination needs SPRINT 2 needed?
 tracks: [ 
    { 
        id: 1,
        name: 'example track', 
        description: 'Simple track to add some basic annotations',
        settings: {
          color: 'blue',
          picture: 'http://icon.org/myTrackIcon.png'
        },
        access: 'public'
    },
    {
        id: 2,
        name: 'George private track', 
        description: 'The private track from George',
        settings: {
          color: 'red',
          picture: 'http://icon.org/anotherIcon.png'
        },
        access: 0,
        updated_by: 123,
 		updated_at: 32421410,
 		created_by: 123,
 		created_at: 32421410 
    }
 ]
}

Update a track

Update the track with the given trackId.

Method Path Parameters HTTP Response
PUT /videos/#{videoId}/tracks/#{trackId} NONE 200 Ok: Resource modified, 304 Not Modified : Resource not modified, 400 Bad request: Request not valid, 401 Unauthorized: Operation not authorized for the user, 404 Not found: Resource not found, 500 Internal server error: Error happened on the server side.

Example request

Url

PUT http://api.annotationstool.com/v1/videos/123/tracks/1

Content

Send the resource parameters as query parameters.

name=example+track&description=simple+track&settings={color:blue,picture=http%3A%2F%2Ficon.org%2FmyTrackIcon.png}&access=1

Response content

Return the status code corresponding the operation done and the Location in the header if resource created.

{
 id: 1,
 name: 'example track', 
 description: 'Simple track',
 settings: '{
    // Some possible settings, not well defined at the moment 
    color: "blue",
    picture: "http://icon.org/myTrackIcon.png"
 }',
 access: 1,
 updated_by: 123,
 updated_at: 32423432,
 created_by: 123,
 created_at: 32421410 
}

Delete a track

Method Path Parameters HTTP Response
DELETE /videos/#{videoId}/tracks/#{trackId} NONE 204 No content: Resource deleted, 401 Unauthorized: Operation not authorized for the user, 404 Not found: Resource not found.

Example request

Url

DELETE http://api.annotationstool.com/v1/videos/123/tracks/1

Content

NO CONTENT

Response content

NO CONTENT

< Rest API documentation [1]: rest-get-parameters