annotator.storage.http

This module provides the ability to send annotations for storage in a remote server that implements the storage-api.

Usage

To use the annotator.storage.http module, you should include it in an instance of annotator.App:

app.include(annotator.storage.http);

You can provide options to the module by passing an additional argument to annotator.App.prototype.include():

app.include(annotator.storage.http, {
    prefix: 'http://example.com/api'
});

See annotator.storage.HttpStorage.options for the full list of options to the annotator.storage.http module.

Storage API

The annotator.storage.http() module talks to a remote server that serves an HTTP API. This section documents the expected API. It is targeted at developers interested in developing their own backend servers that integrate with Annotator, or developing tools that integrate with existing instances of the API.

The storage API attempts to follow the principles of REST, and uses JSON as its primary interchange format.

Endpoints

root

GET /api

API root. Returns an object containing store metadata, including hypermedia links to the rest of the API.

Example request:

GET /api
Host: example.com
Accept: application/json

Example response:

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Content-Length, Content-Type, Location
Content-Length: 1419
Content-Type: application/json

{
    "message": "Annotator Store API",
    "links": {
        "annotation": {
            "create": {
                "desc": "Create a new annotation",
                "method": "POST",
                "url": "http://example.com/api/annotations"
            },
            "delete": {
                "desc": "Delete an annotation",
                "method": "DELETE",
                "url": "http://example.com/api/annotations/:id"
            },
            "read": {
                "desc": "Get an existing annotation",
                "method": "GET",
                "url": "http://example.com/api/annotations/:id"
            },
            "update": {
                "desc": "Update an existing annotation",
                "method": "PUT",
                "url": "http://example.com/api/annotations/:id"
            }
        },
        "search": {
            "desc": "Basic search API",
            "method": "GET",
            "url": "http://example.com/api/search"
        }
    }
}
Request Headers:
 
  • Accept – desired response content type
Response Headers:
 
Status Codes:

read

GET /api/annotations/(string: id)

Retrieve a single annotation.

Example request:

GET /api/annotations/utalbWjUaZK5ifydnohjmA
Host: example.com
Accept: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "created": "2013-08-26T13:31:49.339078+00:00",
    "updated": "2013-08-26T14:09:14.121339+00:00",
    "id": "utalbWjUQZK5ifydnohjmA",
    "uri": "http://example.com/foo",
    "user": "acct:johndoe@example.org",
    ...
}
Request Headers:
 
  • Accept – desired response content type
Response Headers:
 
Status Codes:

create

POST /api/annotations

Create a new annotation.

Example request:

POST /api/annotations
Host: example.com
Accept: application/json
Content-Type: application/json;charset=UTF-8

{
    "uri": "http://example.org/",
    "user": "joebloggs",
    "permissions": {
        "read": ["group:__world__"],
        "update": ["joebloggs"],
        "delete": ["joebloggs"],
        "admin": ["joebloggs"],
    },
    "target": [ ... ],
    "text": "This is an annotation I made."
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "id": "AUxWM-HasREW1YKAwhil",
    "uri": "http://example.org/",
    "user": "joebloggs",
    ...
}
Parameters:
  • id – annotation’s unique id
Request Headers:
 
Response Headers:
 
Response JSON Object:
 
  • id (string) – unique id of new annotation
Status Codes:

update

PUT /api/annotations/(string: id)

Update the annotation with the given id. Requires a valid authentication token.

Example request:

PUT /api/annotations/AUxWM-HasREW1YKAwhil
Host: example.com
Accept: application/json
Content-Type: application/json;charset=UTF-8

{
    "uri": "http://example.org/foo",
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "id": "AUxWM-HasREW1YKAwhil",
    "updated": "2015-03-26T13:09:42.646509+00:00"
    "uri": "http://example.org/foo",
    "user": "joebloggs",
    ...
}
Parameters:
  • id – annotation’s unique id
Request Headers:
 
Response Headers:
 
Status Codes:

delete

DELETE /api/annotations/(string: id)

Delete the annotation with the given id. Requires a valid authentication token.

Example request:

DELETE /api/annotations/AUxWM-HasREW1YKAwhil
Host: example.com
Accept: application/json

Example response:

HTTP/1.1 204 No Content
Content-Length: 0
Parameters:
  • id – annotation’s unique id
Request Headers:
 
  • Accept – desired response content type
Response Headers:
 
Status Codes:

Storage implementations

You can find a list of compatible backends implementing the above API on the GitHub wiki.