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

Sun Dec 28 17:56:37 UTC 2014

Hi all,

Another update.

After testing and refactoring … version 1.0.0 is finally out ~> https://rubygems.org/gems/annotator_store

Thanks.

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

> On Dec 27, 2014, at 6:56 PM, King'ori J. Maina <j at kingori.co> wrote:
> 
> 
> Hi all,
> 
> Just an update for the annotator_store Rails engine <https://github.com/itsmrwave/annotator-store#annotator-store> …  it now covers Rails >= 4.0 and Ruby >= 1.9.3 and two databases … i.e.
> 
> Supported Ruby versions:
> 1.9.3
> 2.0.0
> 2.1.0
> 2.1.1
> 2.1.2
> Supported Rails versions:
> 4.0.x
> 4.1.x
> 4.2.x
> Supported databases:
> MySQL
> PostgreSQL
> CI build matrix captures each setup <https://travis-ci.org/itsmrwave/annotator-store/builds/45224890> i.e. 30 possible configurations.
> 
> Releases with their respective changes can be viewed here <https://github.com/itsmrwave/annotator-store/releases>. It’s now at v0.4.0, gearing up for a stable, full featured and tested v1.0.0.
> 
> Now extending your Rails app to be a annotator store is a cinch! ... see here for installation details: https://github.com/itsmrwave/annotator-store#installation <https://github.com/itsmrwave/annotator-store#installation>
> 
> — King’ori Maina (kingori.co <http://kingori.co/>)
> 
> 
>> On Nov 5, 2014, at 5:58 PM, Benjamin Young <bigbluehat at hypothes.is <mailto:bigbluehat at hypothes.is>> wrote:
>> 
>> On Wed, Nov 5, 2014 at 9:22 AM, King'ori J. Maina <j at kingori.co <mailto:j at kingori.co>> wrote:
>>> 
>>> A final comment is that returning the annotation body would prevent an
>>> additional HTTP roundtrip (since it would return an object with annotated
>>> values).
>> 
>> Yep! That's useful if you expect the server to add anything to the
>> resource representation and need to update any local display or cache
>> of that representation. However, if what you have in your client will
>> === what the server would send back after storage, then responding
>> with metadata (and not doing a second GET request...unless you really
>> wanted too), may be preferable.
>> 
>> Client's that properly watch for the two scenarios, really shouldn't
>> care, though. :)
>> 
>> Ideally... ;)
>> 
>> Great discussion, all!
>> 
>>> 
>>> Thanks all for the feedback and discussion.
>>> 
>>> — King’ori Maina (kingori.co <http://kingori.co/>)
>>> 
>>> On Nov 5, 2014, at 4:08 PM, Benjamin Young <bigbluehat at hypothes.is <mailto:bigbluehat at hypothes.is>> wrote:
>>> 
>>> On Wed, Nov 5, 2014 at 8:51 AM, King'ori J. Maina <j at kingori.co <mailto:j at kingori.co>> wrote:
>>> 
>>> 
>>> Makes sense.
>>> 
>>> Benjamin, just to confirm … that would be 201 + Content-Location headers +
>>> annotation body right?
>>> 
>>> Your quote mentions that the location header would indicate that the current
>>> payload (annotation body?) is a current representation of the newly created
>>> resource.
>>> 
>>> 
>>> Correct. The scenarios (from Nick's list earlier) for 201 are:
>>> 
>>> b. 201 with annotation body
>>> c. 201 with metadata body/headers
>>> 
>>> Scenario b. would include Location and Content-Location headers to
>>> make it clear that the representation returned is the newly created
>>> resource.
>>> 
>>> In the case of c. you'd return a confirmation / meta response that
>>> references where the new thing was made via the Location header, but
>>> makes no further claim that the thing returned is a representation of
>>> any resource by *not* including a Content-Location header (as the
>>> content returned is simply a notification / confirmation response and
>>> not the representation of the new resource).
>>> 
>>> Case c. is what Apache CouchDB does:
>>> http://docs.couchdb.org/en/1.6.1/api/database/common.html#post--db <http://docs.couchdb.org/en/1.6.1/api/database/common.html#post--db>
>>> Sends an "ok": true message + Location with the URI of the new document.
>>> 
>>> Both scenarios have their value. The advantage of b. is that the
>>> client gets the entire representation of the resource (which may
>>> include changes to the resource made by the server) vs. just a
>>> confirmation message. However, if the client doesn't need the full
>>> (possibly different) representation sent back from the server in order
>>> to continue doing it's thing, then c. is preferable as it's generally
>>> a smaller request.
>>> 
>>> Really just depends on how the client can / will / should be written.
>>> 
>>> Thinking I need to get back to finishing those Store API docs now. ;)
>>> 
>>> Thanks, King'ori,
>>> Benjamin
>>> 
>>> 
>>> 
>>> — King’ori Maina (kingori.co)
>>> 
>>> On Nov 4, 2014, at 4:19 PM, Benjamin Young <bigbluehat at hypothes.is> wrote:
>>> 
>>> On Tue, Nov 4, 2014 at 7:36 AM, Nick Stenning <nick at whiteink.com> wrote:
>>> 
>>> On Mon, Nov 3, 2014, at 22:45, Benjamin Young wrote:
>>> 
>>> 
>>> Well...the semantics of 303's definition isn't specific to "new"
>>> resources per say just "other." Quoting from RFC 7231 [1]:
>>> 
>>> 
>>> Sure. I wasn't trying to imply it was specific to new resources.
>>> 
>>> 
>>> Right. I know. :) The point is that 303's in response to a POST is
>>> intentionally vague--as it's uses are vast. ;)
>>> 
>>> The 201 preference stated here is 'cause it says "Created" right there
>>> in the status code. :)
>>> 
>>> 
>>> But that scenario seems quite different from annotation--as the user
>>> rarely wants to go off to the resource they just made and would rather
>>> stay focused on the resource they're annotating.
>>> 
>>> [...]
>>> 
>>> So, if you return a 201, you should refer to the newly created resource in a
>>> Location header (as with a 303) with the disadvantage that browsers
>>> won't interpret this as a redirect.
>>> 
>>> 
>>> This is by design and precisely why the use of 201 should be preferred
>>> in this and similar cases. 201 maintains the state of "creating" for
>>> the UI while 303 takes the user's focus to the thing created. Both are
>>> valuable tools, but not interchangeable.
>>> 
>>> 
>>> The user's focus isn't taken anywhere, because we're discussing the use
>>> of status codes in an API, not a human interface.
>>> 
>>> 
>>> Right. It's the focus on a non-human interface (ignoring docs, and the
>>> poor client programmer for a moment ;) ) that gives us the option to
>>> "do it right" with dealing with (fewer) Web Browser misadventures.
>>> 
>>> The reality is that
>>> current annotator storage implementations assume that the response from
>>> a create POST contains a representation of the created annotation.
>>> 
>>> 
>>> This is totally fine, btw. :)
>>> 
>>> The piece missing is the provision of a "Content-Location" header.
>>> Quoting from 7231:
>>> 
>>> "For a 201 (Created) response to a state-changing method, a
>>> Content-Location field-value that is identical to the Location
>>> field-value indicates that this payload is a current
>>> representation of the newly created resource."
>>> http://tools.ietf.org/html/rfc7231#section-3.1.4.2
>>> 
>>> Think that's the answer to the debate. :)
>>> 
>>> Perhaps you would argue that this isn't sensible, but *if* it is this
>>> way, then in the absence of other factors I would maintain that of the
>>> available options
>>> 
>>> a. 200 with annotation body
>>> b. 201 with annotation body
>>> c. 201 with metadata body/headers
>>> d. 303 to annotation resource URI which in turn returns 200 with
>>> annotation body
>>> 
>>> then option d) remains preferable. Options a) and b) return misleading
>>> information about the URI of the created resource, while option c) is
>>> not backwards-compatible: it requires additional client logic and
>>> another HTTP roundtrip.
>>> 
>>> 
>>> Given the above bit about the "Content-Location" header, I think
>>> option b) is again preferable. It should be a minor tweak to storage
>>> providers which--from what I'm understanding--are already returning
>>> 201's anyhow.
>>> 
>>> 
>>> Sadly, this is probably all academic, as the whole reason the store does
>>> option b) at the moment is that browsers haven't historically agreed on
>>> how to implement CORS across redirects.
>>> 
>>> 
>>> Ah CORS...
>>> 
>>> 201 + Content-Location headers should do the trick then. ^_^
>>> 
>>> Thanks for the RESTful geekery, Nick. ;)
>>> 
>>> Later,
>>> Benjamin
>>> 
>>> 
>>> -N
>>> 
>>> _______________________________________________
>>> 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/20141228/508da084/attachment-0004.html>