Skip to content

Latest commit

 

History

History
224 lines (176 loc) · 7.87 KB

Rest-category.md

File metadata and controls

224 lines (176 loc) · 7.87 KB

#Category

< Rest API documentation

The category resources are related to a video. Enhanced annotation are based on label that are grouped in category. The base path for categories is http://api.annotationstool.com/v1/videos/#{videoId}/categories. But of course a category can be supported by multiple videos. To work on unique categories the following path can be used http://api.annotationstool.com/v1/categories.

Base URI

http://api.annotationstool.com/v1/categories for "template" categories. http://api.annotationstool.com/v1/videos/#{videoId}/categories for copied categories from template.

Attributes

Name Type Description Default
id* Long The category id. Generated at creation
name* String The category name. EMPTY
description String The category description. EMPTY
scale_id Scale id The scale that can be used for this category. NULL
settings String Dictionnary of diverse metadata related to the category NULL
tags String String of related tags. NULL
+ logging attributes

* = required

Operations

Create a new category

Create a new "template" category.

Method Path Parameters HTTP Response
POST /categories NONE 201 Created: Resource created, 400 Bad request: Request not valid, 401 Unauthorized: Operation not authorized for the user, 409 conflict: Resource already exist, 500 Internal server error: Error happened on the server side.

Example request

Url

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

Content

`name=Feelings&description=Category+containing+the+feelings+visible+in+the+video&scale_id=4

Response content

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

{
 id: 23,
 name: 'Feelings', 
 description: 'Category containing the feelings visible in the video',
 scale_id: 12,
 access: 0,
 updated_by: 123,
 updated_at: 32421410,
 created_by: 123,
 created_at: 32421410, 
}

Add a category to a video

Add a given category to the video with id videoId. The category (with the id category_id) will be copied and attached to the video. The label and the scale from the template category will also be copied to the category copy.

  • The category will be copied from /categories/#{categoryId} to /videos/#{videoId}/categories/#{newCopyCategoryId}.

  • The labels will be copied from /categories/#{categoryId}/labels to /videos/#{videoId}/categories/#{newCopyCategoryId}/labels. All the copy of the labels will then have new id.

  • The scale will be copied from /scales/#{scaleId} to /videos/#{videoId}/scales/#{newCopyScaleId}.

  • The scale values will be copied from /scales/#{scaleId}/scalevalues to /videos/#{videoId}/scales/#{scaleId}/scalevalues. All the copy of the scale vaules will then have new id.

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

Example request

Url

POST http://api.annotationstool.com/v1/videos/123/categories?category_id=23

Content

EMPTY

Response content

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

{
 id: 24,
 name: 'Feelings', 
 description: 'Category containing the feelings visible in the video',
 scale_id: 12,
 access: 0,
 updated_by: 123,
 updated_at: 32421434,
 created_by: 123,
 created_at: 32421434, 
}

Get a category

Get a category with the id categoryId

Method Path Parameters HTTP Response
GET /videos/#{videoId}/categories/#{categoryId} or /categories/#{categoryId} 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/v1/videos/123/categories/23

Content

NO CONTENT

Response content

{
 id: 23,
 name: 'Feelings', 
 description: 'Category containing the feelings visible in the video',
 scale_id: 12,
 access: 0,
 updated_by: 123,
 updated_at: 32421434,
 created_by: 123,
 created_at: 32421434 
}

Get all categories from a video

Query categories from a video.

Method Path Parameters HTTP Response
GET /videos/#{videoId}/categories or /categories list queries parameters 200 Ok: Resources 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.

Default sorting

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

Example request

Url

GET http://api.annotationstool.com/v1/videos/123/categories?limit=2&offset=0

Content

NO CONTENT

Response content

{
 count: 2, // Result lenght
 offset: 0, // Offset parameter to use in case of pagination needs
 items: [
    {
        id: 23,
 		name: 'Feelings', 
 		description: 'Category containing the feelings visible in the video',
 		scale_id: 12,
 		access: 0,
 		updated_by: 123,
 		updated_at: 32421434,
 		created_by: 123,
 		created_at: 32421434 
 	 },
 	…
 ]
}

Update an category

Update the category with the given categoryId or create a new one with this categoryId.

Method Path Parameters HTTP Response
PUT /videos/#{videoId}/categories/#{categoryId} or /categories/#{categoryId} NONE 200 Ok: Resource modified, 201 created: Resource created, 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.

FORM Parameters

Example request

Url

PUT http://api.annotationstool.com/v1/videos/123/categories/23

Content

Send the resource parameters as query parameters.

name=Users+Feelings&description=Category+containing+the+feelings+visible+in+the+video&scale_id=5

Response content

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

{
 id: 23,
 name: 'Feelings', 
 description: 'Category containing the feelings visible in the video',
 scale_id: 4,
 access: 1,
 updated_by: 123,
 updated_at: 32423412,
 created_by: 123,
 created_at: 32421410, 
}

Delete a category

Method Path Parameters HTTP Response
DELETE /videos/#{videoId}/categories/#{categoryId} or /categories/#{categoryId} 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/categories/23

Content

NO CONTENT

Response content

NO CONTENT

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