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

Wed Nov 5 14:08:29 UTC 2014

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
>
>