Skip to content

Latest commit

 

History

History
172 lines (141 loc) · 5.31 KB

Rest-comment.md

File metadata and controls

172 lines (141 loc) · 5.31 KB

Comment

< Rest API documentation

Base URI

The comment resources are related to an annotation. The base path for them is

http://api.annotationstool.com/v1/videos/#{videoId}/tracks/#{trackId}/annotations/#{annotationId}/comments

Attributes

Name Type Description Default
id* Long The comment id. Generated at creation
text* String The comment text. EMPTY
+ logging attributes

* = required

Operations

Add a new comment to an annotation

Add the given comment to the annotation with id annotationId. The comment id must not be given.

Method Path Parameters HTTP Response
POST /videos/#{videoId}/tracks/#{trackId}/annotations/#{annotationId}/comments text 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/#{videoId}/tracks/#{trackId}/annotations/#{annotationId}/comments

Content

text=Dies ist ein Kommentar

Response content

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

NO CONTENT

Get a comment

Get the comment with the id commentId

Method Path Parameters HTTP Response
GET /videos/#{videoId}/tracks/#{trackId}/annotations/#{annotationId}/comments/#{commentId} 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/#{videoId}/tracks/#{trackId}/annotations/#{annotationId}/comments/12

Content

NO CONTENT

Response content

{
 id: 12,
 text: 'Dies ist ein Kommentar',
 access: 0,
 updated_by: 123,
 updated_at: 32421410,
 created_by: 123,
 created_at: 32421410 
}

Get all comments from an annotation

Query comments from an annotation.

Method Path Parameters HTTP Response
GET /videos/#{videoId}/tracks/#{trackId}/annotations/#{annotationId}/comments 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.

Example request

Url

GET http://api.annotationstool.com/v1/videos/#{videoId}/tracks/#{trackId}/annotations/#{annotationId}/comments?limit=4

Content

NO CONTENT

Response content

{
 count: 4, // Result length
 offset: 0, // Offset parameter to use in case of pagination needs
 comments: [
        {
 		id: 12,
 		text: 'Dies ist ein Kommentar',
 		access: 0,
 		updated_by: 123,
 		updated_at: 32421410,
 		created_by: 123,
 		created_at: 32421410 
	},
        {
 		id: 13,
 		text: 'Hallo Welt', 
 		access: 0,
 		updated_by: 123,
 		updated_at: 32421411,
 		created_by: 123,
 		created_at: 32421411 
	},
	{
 		id: 14,
 		name: 'Sehr gute Annotation', 
 		access: 0,
 		updated_by: 123,
 		updated_at: 32421412,
 		created_by: 123,
 		created_at: 32421412 
	},
	{
 		id: 15,
 		name: 'Diese Annotation ist falsch', 
 		access: 0,
 		updated_by: 123,
 		updated_at: 32421412,
 		created_by: 123,
 		created_at: 32421412 
	}
 ]
}

Update or create a comment

Update the comment with the given commentId or create a new one with this commentId.

Method Path Parameters HTTP Response
PUT /videos/#{videoId}/tracks/#{trackId}/annotations/#{annotationId}/comments/#{commentId} text 200 Ok: Resource modified, 201 created: Resource created.

Example Request

Url

PUT http://api.annotationstool.com/v1/videos/#{videoId}/tracks/#{trackId}/annotations/#{annotationId}/comments/12

Content

text=Dies ist ein Kommentar

Response Content

{
 id: 12,
 text: 'Dies ist ein Kommentar'
}

Response Header

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

Delete a comment

Delete the comment with id commentId.

Method Path Parameters HTTP Response
DELETE /videos/#{videoId}/tracks/#{trackId}/annotations/#{annotationId}/comments/#{commentId} 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/#{videoId}/tracks/#{trackId}/annotations/#{annotationId}/comments/12

Content

NO CONTENT

Response content

NO CONTENT

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