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

[Nick Stenning]

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.

> 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. The reality is that
current annotator storage implementations assume that the response from
a create POST contains a representation of the created annotation.
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.

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.

-N