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

Wed Nov 5 13:51:37 UTC 2014

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.

— King’ori Maina (kingori.co <http://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/28fcd236/attachment-0004.html>