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

Sat Dec 27 16:56:15 UTC 2014

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

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

> On Nov 5, 2014, at 5:58 PM, Benjamin Young <bigbluehat at hypothes.is> wrote:
> 
> On Wed, Nov 5, 2014 at 9:22 AM, King'ori J. Maina <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)
>> 
>> On Nov 5, 2014, at 4:08 PM, Benjamin Young <bigbluehat at hypothes.is> wrote:
>> 
>> On Wed, Nov 5, 2014 at 8:51 AM, King'ori J. Maina <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
>> 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/20141227/de18322c/attachment-0003.html>