AnnotationAPI

Draft 2015-06-05

Get annotation details

Endpoint: /annotation/annID
Method: GET
Request body: none
Response body: {"id":81538,"startOffset":1938,"endOffset":1938,"target":null,"selector":null,"type":"g","purpose":"NONE","content":null,"attributes":"{\"ref\":\"#slash\"}","modifiedBy":0,"approvedBy":0,"startPage":17000,"endPage":17000,"bounds":null,"canvas":null}
Status: 200 on success, 404 if annID does not exist.

Set annotation details

Endpoint: /annotation/annID
Method: PUT
Request body: {"content":"/"}
Response body: none
Status: 204 on success, 404 if annID does not exist.
Comments:
The JSON object in the request body should contain all fields which are to be modified; fields which aren't being changed can be omitted.

Add a sub-annotation

Endpoint: /annotation/annID₁/annotations
Method: POST
Request content-type: application/json
Request body: {"type":"colour","content":"turquoise"}
Response body: none
Response location: /annotation/annID₂
Status: 201 on success, 404 if annID₁ does not exist.
Comments:
The request body should contain a single annotation object. The Location header of the response gives the caller the ID of the newly-created annotation.

Get sub-annotations

Endpoint: /annotation/annID/annotations
Method: GET
Request body: none
Response body: Array of annotations attached to annID.
Status: 200 on success, 404 if annID does not exist.
Comments:
Response contains an array with all annotations attached the given annotation.

Set sub-annotations

Endpoint: /annotation/annID/annotations
Method: PUT
Request body: Array of new annotations to be attached to annID.
Request parameters: merge=true|false (default true)
Response body: none
Status: 204 on success, 404 if annID does not exist.
Comments:
The JSON array in the request body should contain new values for the annotation's sub-annotations. If the merge parameter is false, the existing sub-annotations will be completely replaced; if it is true or omitted, only annotations mentioned in the request body will be affected.

Approve an annotation

Endpoint: /annotation/annID/approval
Method: PUT
Request body: none
Response body: none
Status: 204 on success, 403 if the user does not have EDITOR permission on annID, 404 if annID does not exist.
Comments:
Sets the approvedBy field of the annotation to the ID of the current user.

Delete an annotation

Endpoint: /annotation/annID
Method: DELETE
Request body: none
Response body: none
Status: 204 on success.
Comments:
Deletes the single annotation identified by annID.