[annotator-dev] Upcoming changes to Annotator and the Annotator Store

Tue Jan 31 23:35:18 UTC 2012

Hi all,

In order for this email to make any sense, I'm going to need to
provide a little bit of historical/technical background. In short, the
authentication system for AnnotateIt (http://annotateit.org) was in
serious need of an overhaul to bring it in line with what Annotator
was originally designed for. In particular, we want people to be able
to use AnnotateIt as a service in which to store not just their own
annotations, but also those of their users.

The way this was originally intended to work goes as follows:

1) Alice builds a website with documents which need annotating, DocLand.

2) Alice registers DocLand with AnnotateIt, and receives a "consumer
key/secret" pair.

3) Alice's users (Bob is one of them) login to her DocLand, and
receive an authentication token, which is a cryptographic hash of
(among other things) their unique user ID at DocLand, and DocLand's
"consumer secret".

4) Bob's browser sends requests to AnnotateIt to save annotations, and
these include the authentication token as part of the payload.

5) AnnotateIt can verify the Bob is a real user from DocLand, and thus
stores his annotation.

Now, due to time constraints, this isn't really how AnnotateIt works
at the moment, and the code got a little confused about the
distinction between users (Bob) and consumers (DocLand). This wasn't
helped by the fact that AnnotateIt is one of its own consumers (we
provide people with bookmarklets which allow them to annotate anything
on the web).

Over the past few days I've been working to resolve this confusion,
and I'm slowly getting there. You can see the work at:

https://github.com/okfn/annotator-store/commits/feature/es+sql
https://github.com/okfn/annotator/commits/feature/fixauth

The key features of the new system are as follows:

1) Users of AnnotateIt will be able to use a bookmarklet to annotate
around the web, as before. This bookmarklet will now no longer contain
any code or data which, if stolen, would result in the compromise of
your AnnotateIt account.

2) When you click the bookmarklet, you'll (finally) be able see the
annotations of *any* AnnotateIt user who's annotated that page and
elected for their annotations to be public.

3) Users of AnnotateIt will be able to register for multiple consumer
key/secret pairs, just like you (used to) apply for Google Maps API
keys.

4) Allowing registered AnnotateIt users to annotate your website is
now a blindingly trivial two lines of code (once you've included
Annotator's source files):

    $('body').annotator()
             .annotator('setupPlugins');

5) Annotations are now stored in ElasticSearch, meaning that the
future looks bright for full-text search and analytics over the
annotation database.

I'll be keeping you posted when I get the code into a stable state,
after which I hope we'll be able to migrate the data that's currently
in AnnotateIt's CouchDB store, and get moving with a better, more
flexible authentication system.

In the meantime, I'd appreciate any comments or criticisms. Feel free
to dive in on Github and comment on commits and issues, or reply here.

Best,
Nick