Reference implementation backend for Annotator web annotation system.

Defines the reference RESTFul API and connects to a database backend to persist annotations created by the frontend, Annotator_.

.. _Annotator: http://github.com/nickstenning/annotator

There is also an experimental CouchDB implementation. See the couchdb branch of the repository.

Getting Started

The following instructions assume you have a working installation of python (2.6 or higher) and sqlite (any recent version). You will also need pip and virtualenv, which can be installed quickly with one command::

easy_install virtualenv

Now, you should be ok to set up annotator-store-py::

git clone git://github.com/nickstenning/annotator-store-py.git
cd annotator-store-py
pip install -E pyenv -r requirements.txt -e .

If that worked ok, you should see something like::

[...]
Successfully installed annotator HTTPEncode httplib2 Paste PasteDeploy PasteScript routes SQLAlchemy webob wsgifilter
Cleaning up...

You should now be able to run the demo server::

source pyenv/bin/activate
paster serve store.ini

You might a deprecation warning from SQLAlchemy. We're working on removing this but in the mean time you can safely ignore it. You can take a peek at the (little) that the backend is now doing::

curl -i http://localhost:5000/annotations

You'll see that the store responds with "[]": there aren't any annotations in the store at the moment. That's not surprising: you haven't created any. For that, you'll need to go get Annotator_ and hook it up to the backend.

RESTFul Interface

The RESTful interface is provided by the WSGI application in annotator/store.py.

It can be mounted anywhere you like and provides a RESTful resource 'annotations'.

For example if you have mounted it at '/store' you would have::

GET    /store/annotations      # list
POST   /store/annotations      # create
GET    /store/annotations/{id} # show
PUT    /store/annotations/{id} # update
DELETE /store/annotations/{id} # delete

Attributes for these methods (in particular annotation values) may be provided either as individual query parameters or as as json payload (encoded in standard way as argument to a parameter named json). Returned data will be JSON encoded. If a "callback" query parameter is supplied, any response will be JSONP encoded using the value of "callback" as the name of the callback function.

Notes:

A create request returns a Location header redirecting to the created
annotation.

Searching

Search API is located at: {mount_point}/annotations/search

Results are returned in JSON format::

{
    'total': number of results,
    'results': results list
}

You can search by any annotation attribute (but not "extras"). For example to search for annotation with a particular 'uri' field you'd visit::

/annotations/search?uri=http://example.com

In addition to search parameters there are three additional control parameters:

limit=val: limit the number of results returned to val (defaults to 100 if
not set). To have all results returned set to -1.
offset=val: return results from val onwards
all_fields=1: if absent only return ids of annotations, if present (true)
return all fields of the annotation

Specification of Annotations

Annotations can have the following attributes:

id: unique identifier of the annotation -- usually provided by the store at creation.
uri: document identifier
user: an identifier for the user who created the annotation. To avoid
cross-application collision it is recommended that you either:
- Generate uuids for your users stored as: urn:uuid:{uuid} (or just {uuid})
- (or) Prefix your usernames with a unique (e.g. uuid) string (e.g. {uuid-identifying-application}::{your-username}
text: text of annotation
range(s): list of range objects. Each range object has:
- [optional] format: range format (defines syntax/semantics of start end)
- start: xpath, offset (for default html format)
- end: xpath, offset (for default html format)
[optional] quote (the quoted text -- or snippet thereof)
[optional] created (datetime of creation)

You can also add arbitrary additional key/value pairs to annotations, these are serialized as "extras" in the database in this version of the annotation store.

Changelog

HEAD

v0.4 2010-11-10

Beta release: this annotator store has now been successfully used in production deployments.

New attributes on Annotation: user, tags
Support for jsonp and returning id on annotation create
Allow arbitrary attributes on annotations
Searching annotations (essential for multi-document annotation!)
Improved documentation
Support locating annotation RESTFul url within store (e.g.
{store}/annotations instead {store}/annotation)
Preliminary CORS support for cross-domain requests
Preliminary CouchDB support

v0.3 2009-10-18

Major release:

RESTful interface is JSON-based by default
Much improved demo with WSGI middleware
Switch from existing marginalia js library to new jsannotate library
Rename from annotater to annotator
Make model code easily reusable inside another project
Simplify and refactor code throughout

v0.2 2009-07-26

Significant polishing
Convert backend store to use SQLAlchemy
Load RESTful interface at an arbitrary url
Last version to be based on marginalia

v0.1 2007-04-01

Fully functioning web annotation using marginalia
SQLObject based backend store
WSGI RESTful interface to store
WSGI app for mounting marginalia media (js, css etc)
Demo app in demo/

Copyright and License

Licensed under the MIT license:

http://www.opensource.org/licenses/mit-license.php

Versions earlier than 0.3 used js code derived from Geof Glass' code which are therefore (c) Geoff Glass and collaborators and are licensed under the GPL v2.