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

Mon Nov 3 15:07:40 UTC 2014

201 Created for the create action sounds perfect. I’ll test this and push it up as soon as I can.

For the update I think 200 OK is more suitable … googling around 202 Accepted is used when ‘The request has been accepted but has not been processed yet. This code does not guarantee that the request will process successfully.’ … which doesn’t apply in this case.

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

> On Nov 3, 2014, at 4:57 PM, Benjamin Young <bigbluehat at hypothes.is> wrote:
> 
> 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
>> 

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