Subject: Link and Unlink

From: James M Snell <[email-masked]>
Date: Mon, 8 Oct 2012 13:28:16 -0700

For review and comment...

  http://www.ietf.org/id/draft-snell-link-method-00.txt

Updated definition of LINK and UNLINK, taking RFC5988 into consideration
and using language consistent from current httpbis draft (read: shamelessly
and remorselessly lifted).

Comments and feedback definitely welcome.

- James

---

From: Amos Jeffries <[email-masked]>
Date: Tue, 09 Oct 2012 13:49:43 +1300

> Comments and feedback definitely welcome.

Given that LINK/UNLINK contain the active parameters for change in Link 
headers instead of URL I don't believe they are normally cacheable as 
stated in the draft. Only when a proxy cache is performing conditional 
requests to the upstream server does cacheability make sense.

For example; two LINK requests for the same URL with different Link 
header content. Request A and request B.

Request A can happen and have a response. However request B, should not 
(MUST NOT?) be responded to by a proxy cache using a cached response to 
request A since the intended server/target of LINK will never receive 
the (different) request-B Link headers. It is likely that the request B 
will have created a different response body to request A anyway 
(use-case being a registry index of some sort, ie torrent seeders list, 
library index, database table content) - making caching the most 
undesirable of outcomes.

The same use-case applies to UNLINK headers and responses.

Also the referenced part6 draft states
" A cache MUST write through requests with methods that are unsafe
    (Section 5.2.1 of [Part2]) to the origin server; i.e., a cache is 
not
    allowed to generate a reply to such a request before having 
forwarded
    the request and having received a corresponding response.
"

So the non-conditional cases passing the request through and waiting 
for a new 2XX response before responding makes caching the earlier 
response useless. For the browser/client cache situation the response 
would seem to be only needed to update the client state information then 
can be discarded.

On the other hand ...

If the proxy cache were to relay the request but add conditional 
headers. Making request-B potentially not only make the LINK/UNLINK 
update but query whether the cached 2xx response is suitable for sending 
to the client.
NP: only the If-Match/If-None-match conditionals make since for this 
case, the time-based ones would block a clients unconditional change.

That raises the question of whether, being idempotent the server should 
respond with "304 Not Modified" in all cases where the LINK/UNLINK was 
not performed due to the link already existing (or not). 204 seems to be 
a step in that direction while retaining the 200 semantics, but 204 
*replaces* a 200 representation with 'nothing' - whereas 304 would 
simply be a no-op success.

Amos

---

From: James M Snell <[email-masked]>
Date: Mon, 8 Oct 2012 19:15:11 -0700

On Mon, Oct 8, 2012 at 5:49 PM, Amos Jeffries <[email-masked]> wrote:

>>   http://www.ietf.org/id/draft-**snell-link-method-00.txt<http://www.ietf.org/id/draft-snell-link-method-00.txt>
>>
Definitely appreciate the detailed look through. I've been going through a
variety of use cases this afternoon and I'm less and less convinced that
allowing caching for link/unlink is useful for any reason whatsoever. I
can't really think of a single case where it may be worthwhile.

> [snip]
> respond with "304 Not Modified" in all cases where the LINK/UNLINK was not
> performed due to the link already existing (or not). 204 seems to be a step
> in that direction while retaining the 200 semantics, but 204 *replaces* a
> 200 representation with 'nothing' - whereas 304 would simply be a no-op
> success.
>
>
There are a couple of cases worth considering...specifically, a LINK might
not create a new link, but it might modify an existing one.. namely when
different metadata (title, hreflang, etc) is provided and the link already
exists. Returning a 304 if the Link already exists and has not been
modified makes a lot of sense. This is a case that should definitely be
documented in the doc.

One of the other major questions that came up for me when thinking this
through is what if the Link Relationship itself can be created as a
resource? For instance...

Request:

  LINK /my-resource HTTP/1.1
  Host: example.org
  Link: <http://example.org/foo>; rel="foo"

Response:

  HTTP/1.1 201 Created
  Location: http://example.org/a-link-resource

This is definitely an edge case and I'm not sure if this is somewhere we
want to go at all, but such responses should not be ruled out (which also
speaks to the uncacheable nature of the LINK and UNLINK).

- James

  HTTP/1.1

---

From: "Manger, James H" <[email-masked]>
Date: Tue, 9 Oct 2012 14:07:50 +1100

Using Link as an HTTP request header to convey  a link that you want to appear as an HTTP response header only works if requests can never have their own Link headers. Is this true?

It might be better architecturally to send a PATCH request with the new Link headers in the body with, say, an application/header-patch media type.

Perhaps it depends on whether links are particularly special (warranting dedicated HTTP methods), or whether they are basically content metadata(not that different from, say, content-type).

--
James Manger

From: James M Snell [mailto:[email-masked]]
Sent: Tuesday, 9 October 2012 7:28 AM
To: [email-masked]
Subject: Link and Unlink

Updated definition of LINK and UNLINK, taking RFC5988 into consideration and using language consistent from current httpbis draft (read: shamelessly and remorselessly lifted).

- James

---

From: James M Snell <[email-masked]>
Date: Mon, 8 Oct 2012 20:58:55 -0700

On Mon, Oct 8, 2012 at 8:07 PM, Manger, James H <
[email-masked]> wrote:

> Using Link as an HTTP request header to convey  a link that you want to
> appear as an HTTP response header only works if requests can never have
> their own Link headers. Is this true?****
>
> **
>

It may not be obvious but LINK is not really intended to "convey links that
you want to appear as an HTTP response header".. in fact, the LINK method
itself really has nothing to do with what appears within response
headers... it is just a method that can be used to create an explicit
relationship between two resources, and within that request, the Link
header is used to convey the type of link to establish. In this case, I'm
only defining what Link means within the LINK and UNLINK methods and
nothing else.

>  **
>
> It might be better architecturally to send a PATCH request with the new
> Link headers in the body with, say, an application/header-patch media type.
> ****
>
> **
>

-1.. the main point of LINK/UNLINK is so that links can be established
independently of the specific resource or it's representation.

> **
>
> Perhaps it depends on whether links are particularly special (warranting
> dedicated HTTP methods), or whether they are basically content metadata(not
> that different from, say, content-type).
>

This depends entirely on the application case. There are many application
cases I can point to where creating a link between resources is an activity
rather than just a part of the metadata. In such cases, having a LINK
method makes far more sense than dealing with how links happen to be
represented with a particular data format. In fact, there are a large
subset of those cases in which it wouldn't make any sense at all to
serialize the existing links even tho they exist (pub/sub type scenarios
are one such example).

> ****
>
> ** **
>
> --****
>
> James Manger****
>
> ** **
>
> *From:* James M Snell [mailto:[email-masked]]
> *Sent:* Tuesday, 9 October 2012 7:28 AM
> *To:* [email-masked]
> *Subject:* Link and Unlink****
>
> ** **
>
> For review and comment...****
>
> ** **
>
>   http://www.ietf.org/id/draft-snell-link-method-00.txt****
>
> ** **
>
> and remorselessly lifted).  ****
>
> ** **
>
> Comments and feedback definitely welcome.****
>
> ** **
>
> - James****
>
> ** **
>

---

From: James M Snell <[email-masked]>
Date: Tue, 9 Oct 2012 10:28:29 -0700

Quick iteration based on initial feedback. Primary changes around
cacheability and response codes. Some editorial cleanups too..

  http://www.ietf.org/id/draft-snell-link-method-01.txt

- James

On Mon, Oct 8, 2012 at 1:28 PM, James M Snell <[email-masked]> wrote:

> and using language consistent from current httpbis draft (read:
> shamelessly and remorselessly lifted).
>

---

From: Amos Jeffries <[email-masked]>
Date: Wed, 10 Oct 2012 10:08:55 +1300

>   http://www.ietf.org/id/draft-snell-link-method-01.txt

Looks good to me.

Amos

---

From: Julian Reschke <[email-masked]>
Date: Fri, 12 Oct 2012 10:57:06 +0200

> Comments and feedback definitely welcome.

I think it would be good to consider rev= (supported? optional?) and 
anchor= (same).

Best regards, Julian

---

From: Mark Nottingham <[email-masked]>
Date: Sat, 13 Oct 2012 07:32:32 +1100

Personally, I'm -0 on this; I don't see demand for it yet, and we're really just learning how to build link-driven HTTP APIs. YMMV (in which case I'd be glad to hear about detailed use cases!).

Cheers,

--
Mark Nottingham   http://www.mnot.net/

---

From: James M Snell <[email-masked]>
Date: Fri, 12 Oct 2012 14:03:52 -0700

This is one that I'm not in a terribly rush to push through. Publishing the
draft and resurrecting these now is mostly intended to get them on the
table again for people to use and get some experience with. Whether they
ultimately prove to be useful or not definitely has yet to be determined.

There are quite a few use cases where I can see these being used. Many
existing web apis are driven on the concepts of establishing links between
resources.

A Pub/Sub solution, for instance, is fundamentally based on links between
the publisher and a listeners. Using LINK and UNLINK, we could potentially
avoid having to create any kind of subscription management API... the flow
becomes nothing more than LINK and UNLINK calls...

  LINK /my-topic-resource HTTP/1.1
  Host: example.org
  Link: <http://example.com/my-listener>; rel="monitor"

Another case involves linking distributed or federated services to a user
profile...  for instance...

  LINK /profiles/jasnell HTTP/1.1
  Host: example.org
  Link: <http://example.org/my-weblog>; rel="weblog"

Once such a link has been established, a mechanism such as WebFinger could
be used to discover and enumerate such links.

For another case, imagine a collection resource to which we may want to add
an existing resource (as opposed to posting and creating a brand new
resource).

  LINK /some-collection HTTP/1.1
  Host: example.org
  Link: <http://example.com/some-item>; rel="item"

I could easily come up with a dozen more such examples. The main thing for
me right now, however, is getting this out there for folks to start
thinking about and tinkering around with. It gets the discussion started,
at the very least.

- James
On Oct 12, 2012 1:32 PM, "Mark Nottingham" <[email-masked]> wrote:

> Personally, I'm -0 on this; I don't see demand for it yet, and we're
> really just learning how to build link-driven HTTP APIs. YMMV (in which
> case I'd be glad to hear about detailed use cases!).
>
> Cheers,
>
>

---

From: Mark Nottingham <[email-masked]>
Date: Sat, 13 Oct 2012 08:04:58 +1100

On 13/10/2012, at 8:03 AM, James M Snell <[email-masked]> wrote:

> This is one that I'm not in a terribly rush to push through. Publishing the draft and resurrecting these now is mostly intended to get them on the table again for people to use and get some experience with. Whether they ultimately prove to be useful or not definitely has yet to be determined.

Sounds reasonable, thanks. Let's see what happens.