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

[Benjamin Young]

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