Annotations /annotations
¶
/annotations
endpoint provides a way to handle annotations management.
annotations
are structured info that can be related to BEdita objects.
This endpoint provides:
- get a list of annotations
- retrieve data of a single annotation by unique identifier
- create an annotation
- modify an annotation
- remove an annotation
Note: in the following sections, {annotationId}
and (annotation_id)
are sample placeholders for the unique identifier of the annotation, typically an integer number.
{objectId}
is a sample placeholders for the unique identifier of the object.
Other placeholders used in this page are {objectTypeName}
, {description}
, {userId}
, {createdDate}
, {modifiedDate}
, etc.
In the examples, response data contains a reduced number of fields, for better readability.
Get a collection of annotations¶
-
GET
/annotations
¶
Use GET /annotations
to retrieve a collection of annotations.
Available filters are Field filter and Search Query filter.
Example request (get all annotations):
GET /annotations HTTP/1.1
Host: example.com
Accept: application/vnd.api+json
Example response:
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": [
{
"id": "{annotationId}",
"type": "annotations",
"attributes": {
"object_id": "{objectId}",
"description": "{description}",
"params": null
},
"meta": {
"user_id": "{userId}",
"created": "{createdDate}",
"modified": "{modifiedDate}"
},
"links": {
"self": "https://example.com/annotations/{annotationId}"
},
"relationships": {
"object": {
"links": {
"related": "https://example.com/annotations/{annotationId}/object",
"self": "https://example.com/annotations/{annotationId}/relationships/object"
}
},
}
}
],
"links": {
"self": "https://example.com/annotations",
"home": "https://example.com/home",
"first": "https://example.com/annotations",
"last": "https://example.com/annotations",
"prev": null,
"next": null
},
"meta": {
"pagination": {
"count": 2,
"page": 1,
"page_count": 1,
"page_items": 1,
"page_size": 20
}
}
}
Get single annotation¶
-
GET
/annotations/
(annotation_id)¶
Get details for a single annotation by its unique identifier.
Example request (get a single annotation by id):
GET /annotations/{annotationId} HTTP/1.1
Host: example.com
Accept: application/vnd.api+json
Example response:
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {
"id": "{annotationId}",
"type": "annotations",
"attributes": {
"object_id": "{objectId}",
"description": "{description}",
"params": null
},
"meta": {
"user_id": "{userId}",
"created": "{createdDate}",
"modified": "{modifiedDate}"
},
"relationships": {
"object": {
"links": {
"related": "https://example.com/annotations/{annotationId}/object",
"self": "https://example.com/annotations/{annotationId}/relationships/object"
}
}
}
},
"links": {
"self": "https://example.com/annotations/{annotationId}",
"home": "https://example.com/home"
}
}
Create an annotation¶
-
POST
/annotations
¶
Annotation must be referenced to an object and it must have at least a description
.
To create a new annotation, you use POST /annotations
, specifying in the payload:
- the annotations type (
data.type
)- the referenced object (
data.attributes.object_id
)- the annotation description (
data.attributes.description
)
On succeed, response http status is 201 Created
.
Example request (create a new annotation):
POST /annotations HTTP/1.1
Host: example.com
Accept: application/vnd.api+json
{
"data": {
"type": "annotations",
"attributes": {
"object_id": "{objectId}",
"description": "a note"
}
}
}
Example response:
HTTP/1.1 201 Created
Content-Type: application/vnd.api+json
{
"data": {
"id": "{annotationId}",
"type": "annotations",
"attributes": {
"object_id": "{objectId}",
"description": "a note",
"params": null
},
"meta": {
"user_id": "{userId}",
"created": "{createdDate}",
"modified": "{modifiedDate}"
},
"relationships": {
"object": {
"links": {
"related": "https://example.com/annotations/{annotationId}/object",
"self": "https://example.com/annotations/{annotationId}/relationships/object"
}
}
}
},
"links": {
"self": "https://example.com/annotations",
"home": "https://example.com/home"
}
}
Modify an annotation¶
-
PATCH
/annotations/
(annotation_id)¶
Annotation can be modified using PATCH /annotations/{annotationId}
.
Expected fields in body payload:
- the annotation identifier (
data.id
)- the annotations type (
data.type
)- the annotation description (
data.attributes.description
)
On succeed, response http status is 200 OK
.
A basic example follows.
Example request (modify an annotation):
PATCH /annotations/{annotationId} HTTP/1.1
Host: example.com
Accept: application/vnd.api+json
{
"data": {
"id": "{annotationId}",
"type": "annotations",
"attributes": {
"description": "another note"
}
}
}
Example response:
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"data": {
"id": "{annotationId}",
"type": "annotations",
"attributes": {
"object_id": "{objectId}",
"description": "another note",
"params": null
},
"meta": {
"user_id": "{userId}",
"created": "{createdDate}",
"modified": "{modifiedDate}"
},
"relationships": {
"object": {
"links": {
"related": "https://example.com/annotations/{annotationId}/object",
"self": "https://example.com/annotations/{annotationId}/relationships/object"
}
}
}
},
"links": {
"self": "https://example.com/annotations/{annotationId}",
"home": "https://example.com/home"
}
}
Remove annotations¶
-
DELETE
/annotations/
(annotation_id)¶
You can move annotations to trashcan (soft delete) using DELETE /annotations/{annotationId}
, with empty body.
When delete succeeds, 204 No Content
response is returned.
Example request (delete an annotation):
DELETE /annotations/{annotationId} HTTP/1.1
Host: example.com
Accept: application/vnd.api+json
Example response:
HTTP/1.1 204 No Content