Annotations

In Polarity, an annotation is made up of an entity and a tag.  Within the REST API, tags and annotations are synonymous.  An entity can be any value you want to add an annotation/tag to.  For example, you might have the entity 127.0.0.1 and apply the annotation “localhost” to it.  

Every annotation/tag has an id and every entity has an id.  When an annotation is applied to an entity that creates a tag-entity pair which has it’s own id as well.  

Updating Annotations

To update an annotation you need to know the tag-entity id that the annotation is a part of.  You must then send a POST request to the /api/tags endpoint and target the tag-entity pair as a relationship.

curl -v -X POST \
'https://<polarity.server.url>/api/tags' \
--header 'Authorization: Bearer <AUTH_TOKEN>' \
--header 'Content-Type: application/vnd.api+json'
--data-binary @- <<EOF
{
    "data": {
        "attributes": {
            "tag-name": "<UPDATED_ANNOTATION_VALUE>"
        },
        "relationships": {
            "tag-entity-pairs": {
                "data": [
                    {
                        "type": "tag-entity-pairs",
                        "id": "<TAG_ENTITY_PAIR_ID>"
                    }
                ]
            }
        },
        "type": "tags"
    }
}
EOF

import requests
import json

def update_annotation(token, host, new_annotation, tag_entity_pair_id):
    url = f'{host}/api/tags'
    payload = json.dumps({
        'data': {
            'attributes': {
                'tag-name': new_annotation
            },
            'relationships': {
                'tag-entity-pairs': {
                    'data': [
                        {
                            'type': 'tag-entity-pairs',
                            'id': tag_entity_pair_id
                        }
                    ]
                }
            },
            'type': 'tags'
        }
    })

    headers = {
        'Content-Type': 'application/vnd.api+json',
        'Authorization': f'Bearer {token}'
    }

    response = requests.post(url, headers=headers, data=payload)
    response.raise_for_status()

    return response.json()

# Update annotation for the tag-entity paid 50 to the value "updated annotation"
new_annotation = 'updated annotation'
tag_entity_pair_id = '50'
unsubscribe_result = update_annotation(token, HOST, new_annotation, tag_entity_pair_id)

Deleting Annotations

To delete an annotation you just need to know the tag-entity pair id that you wish to remove.  Deleting this id removes the relationship between a specific tag (annotation) and entity.  Once you know the tag-entity pair id, you can send a DELETE request to the /api/tag-entity-pairs/<TAG_ENTITY_PAID_ID> endpoint.  See examples below:

curl -v -X DELETE \
https://<polarity.server.url>/api/tag-entity-pairs/<TAG_ENTITY_PAIR_ID> \
--header 'Authorization: Bearer <AUTH_TOKEN>'

def delete_annotation(token, host, tag_entity_paid_id):
    url = f'{host}/api/tag-entity-pairs/{tag_entity_paid_id}'
     
    headers = {
        #'Content-Type': 'application/vnd.api+json',
        'Authorization': f'Bearer {token}'
    }

    response = requests.delete(url, headers=headers, verify=False)
    response.raise_for_status()

    return response.json()

Finding a Tag-Entity Pair ID

If you are attempting to update a single annotation and need to know the id of the tag-entity pair, you can find this via your browser and the “Explore Annotations” page.  Navigate to the annotation of interest and then click on the annotation in the UI:

Check the URL in the browser and look for the numeric value after the term “comments”.  This numeric value is the tag-entity pair id.  As an example, the URL will look like this:

https://<POLARITY_SERVER>/explore/entity/<ENTITY_ID>/comments/<TAG_ENTITY_PAIR_ID>?option%5BsearchComments%5D=false&option%5BsearchTags%5D=false

If you are searching for the annotation via the parse-entities endpoint, the tag-entity id is the id value under the contexts array.

See searching annotations for more information on how to get the tag-entity pair id.