Skip to content

Latest commit

 

History

History
224 lines (190 loc) · 7.24 KB

Rest-label.md

File metadata and controls

224 lines (190 loc) · 7.24 KB

Label

< Rest API documentation

The label resources are related to a category. The base path for them is http://api.annotationstool.com/v1/categories/#{categoryId}/labels.

Base URI

http://api.annotationstool.com/v1/categories/#{categoryId}/labels for the label related to the template categorie. http://api.annotationstool.com/v1/videos/#{videoId}/categories/#{categoryId}/labels for the category attached to a video.

Attributes

Name Type Description Default
id* Long The label id. Generated at creation
value* String The label value. EMPTY
abbreviation* String The label abriaviation. Should not be more than 2-3 characters. EMPTY
description String The label description. EMPTY
category* category as JSON Object Parent category of this label. EMPTY
settings String Dictionnary of diverse metadata related to the label. NULL
+ logging attributes

* = required

Operations

Add a new label to a category

Add the given label to the category with id categoryId. The label id must not be given . Anyway it will be overwritten.

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

Content

abreviation=%3A)&description=Label+for+happiness&color=44FF&picture=%2Fimages%2Flabels%2Fhappy.png&value=Happy&access=1

Response content

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

{
 id: 1,
 abreviation: ':)', 
 description: 'Label for happiness',
 color: '44FF',
 picture: '/images/labels/happy.png',
 value: 'Happy',
 category: {
 	id: 23,
 	name: 'Feelings', 
 	description: 'Category containing the feelings visible in the video',
 },
 access: 1,
 updated_by: 123,
 updated_at: 32421410,
 created_by: 123,
 created_at: 32421410, 
}

Get a label

Get a label with the id labelId

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

Content

NO CONTENT

Response content

{
 id: 1,
 abreviation: ':)', 
 description: 'Label for happiness',
 color: '44FF',
 picture: '/images/labels/happy.png',
 value: 'Happy',
 category: {
 	id: 23,
 	name: 'Feelings', 
 	description: 'Category containing the feelings visible in the video',
 },
 access: 1,
 updated_by: 123,
 updated_at: 32421410,
 created_by: 123,
 created_at: 32421410, 
}

Get all labels from a category

Query labels from a category.

Method Path Parameters HTTP Response
GET /videos/#{videoId}/categories/#{categoryId}/labels or /categories/#{categoryId}/labels 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 labels list should be sorted by value.

Example request

Url

GET http://api.annotationstool.com/categories/123/labels?limit=2

Content

NO CONTENT

Response content

{
 count: 2, // Result length
 offset: 0, // Offset parameter to use in case of pagination needs
 elements: {
    0: {
 		id: 1,
 		abreviation: ':)', 
 		description: 'Label for happiness',
 		color: '44FF',
 		picture: '/images/labels/happy.png',
 		value: 'Happy',
 		category: {
 			id: 23,
 			name: 'Feelings', 
 			description: 'Category containing the feelings visible in the video',
 		},
 		access: 0,
 		updated_by: 123,
 		updated_at: 32421410,
 		created_by: 123,
 		created_at: 32421410, 
	},
    1: {
 		id: 22,
 		abreviation: ':(', 
 		description: 'Label for sadness',
 		color: '88EE',
 		picture: '/images/labels/sad.png',
 		value: 'Sad',
 		category: {
 			id: 23,
 			name: 'Feelings', 
 			description: 'Category containing the feelings visible in the video',
 		},
 		access: 1,
 		updated_by: 123,
 		updated_at: 32421410,
 		created_by: 123,
 		created_at: 32421410, 
	},
 }
}

Update a label

Update the label with the given labelId or create a new one with this labelId.

Method Path Parameters HTTP Response
PUT /videos/#{videoId}/categories/#{categoryId}/labels or /categories/#{categoryId}/labels/#{labelId} 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.

Example request

Url

PUT http://api.annotationstool.com/v1/categories/123/labels/1

Content

Send the resource parameters as query parameters. abreviation=%3A)&description=Label+for+happiness&color=44FF&picture=%2Fimages%2Flabels%2Fhappy.png&value=Happy&access=0

Response content

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

{
 id: 1,
 abreviation: ':)', 
 description: 'Label for happiness',
 color: '44FF',
 picture: '/images/labels/happy.png',
 value: 'Happy',
 category: {
 	id: 23,
 	name: 'Feelings', 
 	description: 'Category containing the feelings visible in the video',
 },
 access: 0,
 updated_by: 123,
 updated_at: 32423910,
 created_by: 123,
 created_at: 32421410, 
}

Delete a label

Delete the label with id labelId.

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

Content

NO CONTENT

Response content

NO CONTENT

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