[annotator-dev] Yet Another Store Implementation (Ruby/Rails)

Mon Nov 3 10:34:06 UTC 2014

Hi all,

I’ve more or less completed the implementation of Annotator Storage API <http://docs.annotatorjs.org/en/v1.2.x/storage.html> for Ruby/Rails that I mentioned a while back. The gem page is at rubygems.org/gems/annotator-store <http://rubygems.org/gems/annotator-store> and the source code is available at itsmrwave/annotator-store <https://github.com/itsmrwave/annotator-store>.

It’s a Rails engine (versus a standalone implementation) which means that it complements an already existing Rails app (or even a new app) by ‘magically’ adding functional Annotator Store endpoints to your app. This approach offers a couple of benefits … for example, it gives you the benefit of sticking to your own authentication/authorisation approaches (secure the endpoints as you wish!).

During development I used Postgres as the database of choice (at least these were my needs) but since Rails has a well developed ORM this pretty much offers the supported DBs as possible alternatives i.e. MySQL, SQLite etc preventing you from lock-in … this is conjecture at the moment (but I don’t see why not, it should be possible … maybe some tweaking/refactoring here and there).

Adding the engine to your Rails app is a cinch:

Add to Gemfile i.e. the file specifying dependencies and versions … adds 1 line
Install the dependencies in your app (uses Gemfile)  … execute 1 command
Run migrations (creates the tables required) … execute 2 commands
Create a route endpoint to mount the Annotator Store … add 1 line

So in about 5 minutes you have a functioning API endpoints in your app! :-)

I’ve also created a demo Rails app to demonstrate usage here … itsmrwave/annotator-store-demo <https://github.com/itsmrwave/annotator-store-demo>.

Also included in the source are tests covering end-point routing, response requests, models and the controllers. I could add tests for the views i.e. check the JSON responses but figured that maybe that’s overkill. Tests are automated on Travis-CI <https://travis-ci.org/itsmrwave/annotator-store> … all pushes and pull requests should be built.

The API very slightly disagree’s with the Storage API spec on the create and update responses. Currently they respond with 200 OK instead of 303 SEE OTHER but still sets the location URL to the appropriate read endpoint … I’m leaning towards the create and update endpoints to return a object of the created or updated annotation voiding the need of a redirect … and I feel that 200 OK screams success! better. But this is just my opinion I guess.

README’s of the source <https://github.com/itsmrwave/annotator-store#annotator-store> and of the demo application <https://github.com/itsmrwave/annotator-store-demo> have the relevant info and instructions.

Ps: Currently versioned at v0.2.0 (see all releases here <https://github.com/itsmrwave/annotator-store/releases>) … everything is marked as pre-release for now … once I’ve used it for a while, confirmed that it’s stable and feedback from the community is positive … I’ll bump it to v1.0.0 for the first 'production ready’ release.

— King’ori Maina (kingori.co <http://kingori.co/>)

> On Oct 14, 2014, at 4:22 PM, King'ori J. Maina <j at kingori.co> wrote:
> 
> 
> Thanks for the quick response!
> 
> Yes, I see. Been doing some reading and figured that part out and it’s in agreement with your explanation.
> 
> Most of the info out there on the OPTIONS verb seems to point out that it’s used to document an endpoint/API so was just wondering if there’s an Annotator specific purpose.
> 
> Will probably send an update in the next few days.
> 
> — King’ori Maina (kingori.co <http://kingori.co/>)
> 
>> On Oct 14, 2014, at 4:16 PM, Aron Carroll <aron at hypothes.is <mailto:aron at hypothes.is>> wrote:
>> 
>> On 14 Oct 2014, at 16:04, King'ori J. Maina <j at kingori.co <mailto:j at kingori.co>> wrote:
>> 
>>> I’m working on Ruby/Rails powered Annotator storage implementation for Annotator using the Core storage and search API documentation as guides. Seems to be going well so far (though I have a question for the core team at the end of this email).
>> 
>> Awesome!
>> 
>>> That said … for now, I have one question. Why does the plugin make an OPTIONS request to the store? This isn’t in the docs.
>> 
>> That’s a CORS (Cross Origin Resource Sharing) preflight request[1]. It’s not part of the annotator client because it’s performed by the browser when it makes a request to any url that doesn’t match the current document. I recommend reading the linked article. You can choose to handle this in the request handlers of your engine or combine it with something like rack-cors[2].
>> 
>> [1]: http://www.html5rocks.com/en/tutorials/cors/#toc-handling-a-not-so-simple-request <http://www.html5rocks.com/en/tutorials/cors/#toc-handling-a-not-so-simple-request>
>> [2]: https://github.com/cyu/rack-cors <https://github.com/cyu/rack-cors>
>> 
> 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.okfn.org/pipermail/annotator-dev/attachments/20141103/61a634ab/attachment-0003.html>