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