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

Wed Nov 5 14:22:47 UTC 2014

A final comment is that returning the annotation body would prevent an additional HTTP roundtrip (since it would return an object with annotated values).

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> 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/20141105/07bb5199/attachment-0004.html>