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

Mon Nov 3 14:57:20 UTC 2014

Great work, King'ori!

I agree with your analysis that 303 See Other isn't quite the right message.

I'd recommend 201 Created works best for the create action and 200 OK
or 202 Accepted (depending on how you handle processing) are better
for updated.

Likely this HTTP status change is something we should look into for
the next release of the API and JS code.

Thanks again for building an annotator-store endpoint!

On Mon, Nov 3, 2014 at 5:34 AM, King'ori J. Maina <j at kingori.co> wrote:
>
> Hi all,
>
> I’ve more or less completed the implementation of Annotator Storage API for
> Ruby/Rails that I mentioned a while back. The gem page is at
> rubygems.org/gems/annotator-store and the source code is available at
> 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.
>
> 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 … 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 and of the demo application have the relevant info
> and instructions.
>
> Ps: Currently versioned at v0.2.0 (see all releases here) … 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)
>
> 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)
>
> On Oct 14, 2014, at 4:16 PM, Aron Carroll <aron at hypothes.is> wrote:
>
> On 14 Oct 2014, at 16:04, King'ori J. Maina <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
> [2]: https://github.com/cyu/rack-cors
>
>
>
>
> _______________________________________________
> annotator-dev mailing list
> annotator-dev at lists.okfn.org
> https://lists.okfn.org/mailman/listinfo/annotator-dev
> Unsubscribe: https://lists.okfn.org/mailman/options/annotator-dev
>