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

Mon Nov 3 21:45:36 UTC 2014

Ah REST... ;)

On Mon, Nov 3, 2014 at 12:36 PM, Nick Stenning <nick at whiteink.com> wrote:
>
>
> On Mon, Nov 3, 2014, at 06:57, Benjamin Young wrote:
>> Great work, King'ori!
>>
>> I agree with your analysis that 303 See Other isn't quite the right
>> message.
>
> There's nothing wrong with using 303 to refer the client to the newly
> created resource. Indeed, that's exactly the intended use of 303[1].
> You'd POST to a create action, and receive
>
>     HTTP/1.1 303 See Other
>     Location: /annotations/123
>
> to direct the client to the new resource[2].

Well...the semantics of 303's definition isn't specific to "new"
resources per say just "other." Quoting from RFC 7231 [1]:

"It is primarily used to allow the output of a POST action to redirect
the user agent to a selected resource, since doing so provides the
information
corresponding to the POST response in a form that can be separately
identified, bookmarked, and cached, independent of the original
request."

It can (and often is) used by browser / HTML form-based POST requests
to move the browser on to the thing created (or the search results,
etc).

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.

> The only reason the store
> implementation doesn't do this is because browsers didn't correctly
> propagate CORS headers and authorisation across the redirect at the
> time.
>
> It's ok to return 201 from the POST action, but the semantics,
> particularly around caching, are a bit messy.

Some of the more vague language in RFC 2616 about 201 [2] has been
cleared up considerably in RFC 7231 [3].

It's true that the 20* range is not mean for redirection and certainly
shouldn't be used that way. The use of the Location header and/or
links in the body of the response are meant for further traversal by
the user at a (possibly) later time--vs. "I'm taking you there now
'cause the server told me to" (the meaning of 303 See Other).

201's more like a "I made the thing, and put it over here. Carry on
(or go look if you care to." :)

> The body of the response
> in the case of a POST should not, strictly, be a representation of the
> resource created, as its URI is not the URI of the POST endpoint.

True. Both 2616 and 7231 state that the response...
"SHOULD include an entity containing a list of resource
characteristics and location(s) from which the user or user agent can
choose the one most appropriate" -- 2616
...and...
"The 201 response payload typically describes and links to the
resource(s) created." -- 7231

7231 also clarifies that cache semantics around the use of ETag and
Last-Modified for 201:
http://tools.ietf.org/html/rfc7231#section-7.2

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

If none of that cleared it up, these resources are perhaps of deeper
value for further study:
http://httpstatusdogs.com/201-created
httpstatusdogs.com/303-see-other

^_^

Thanks!
Benjamin

[1] http://tools.ietf.org/html/rfc7231#section-6.4.4
[2] http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.2
[3] http://tools.ietf.org/html/rfc7231#section-6.3.2

> -N
>
> [1]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.4
> [2]: https://en.wikipedia.org/wiki/HTTP_303
> _______________________________________________
> 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