auxiliary resource as a role

[pchampin]

this is an alternative proposal to #165

instead of splitting metadata and linkset in terms of representation / resource,
it clarifies that an auxiliary resource is not necessarily disjoint from its primary resource;
the terms do not denote special kinds of resources, but roles that resources play w.r.t. each other (and that, in some circumstances, a resource can play for itself).

What does not change:

• an auxiliary resource is still defined by its lifetime being bound to the primary resource (this is obviously the case if they are the same)

What changes:

• the new definition makes it more explicit that the auxiliary resource has a specific role w.r.t. the primary resource (e.g. its "linkset resource", its "ACL resource"...). I believe that was the intent of the previous definition, but now that is more clearly spelled out.
• the new definition makes it explicit that web links (as per RFC8288 are how auxiliary resources are discovered (but does not currently preclude how those links are conveyed: HTTP headers, in the linkset resources, other ways... possibly in the RDF representation of the resource itself...). I'm not sure this was entirely decided so far.
• the new definition makes it explicit that auxiliary resource and primary resource could be one and the same (with the link pointing to the same URI, as suggested by @acoburn during today's call)

Notes:

• the definition is currently a bit long; some parts of it could be moved in the text of the spec; my goal was to make it clear and easy to review what the proposed direction was.
• I stole some text from @termontwouter 's PR Define aux & meta in terms of representations #165, describing examples of auxiliary resources; thanks to him :)

---

Preview | Diff

[termontwouter]

While I appreciate the alternative proposal, I don't see how it fundamentally differs from the one in #165. Both hold auxiliary information to have a certain role towards a (primary) resource, and to be discoverable through web links.

Moreover, given the discomfort you expressed in #165 with seeing link sets and other 'descriptions' as representations, you should i.m.o. feel the same with the definition in this PR. After all, if you allow that primary and auxiliary resources can be one and the same, you are basically saying that it is okay to serve a resource's representation and its 'description' -- explicitly NOT a representation -- from the same URI, which would on these assumptions still violate HTTP/REST.

That being said, I thus see both PRs as equivalent. My slight preference for #165 over this one is that I feel #165 calls things out more truthfully by their correct terms.

[termontwouter]

As promised in today's meeting, here's an example, highlighting the equivalence with #165. Content and irrelevant headers are omitted for brevity.

Retrieving a Turtle resource

• Request:

  GET /docs/1234 HTTP/1.1
  Host: https://lws.example.org
  Accept: text/turtle
  

• Response when link set URI equals resource URI:

  HTTP/1.1 200 OK
  Content-Type: text/turtle
  Link: </docs/1234> ; rel="linkset"
  

• Response when link set URI does not equal resource URI:

  HTTP/1.1 200 OK
  Content-Type: text/turtle
  Link: </links/1234> ; rel="linkset"
  

Retrieving a Link Set

• Request when link set URI equals resource URI:

  GET /docs/1234 HTTP/1.1
  Host: https://lws.example.org
  Accept: application/linkset, application/linkset+json
  

• Request when link set URI does not equal resource URI:

  GET /links/1234 HTTP/1.1
  Host: https://lws.example.org
  Accept: application/linkset, application/linkset+json
  

• Response when link set URI equals resource URI:

  HTTP/1.1 200 OK
  Content-Type: application/linkset+json
  

• Response when link set URI does not equal resource URI:

  HTTP/1.1 200 OK
  Content-Type: application/linkset+json
  Content-Location: </links/1234>
  

---

Importantly, all the messages above are correct both in PR #165 and in PR #167.

• The only PRACTICAL difference is that in Define aux & meta in terms of representations #165, the client can COUNT on content negotiation for the link set to be possible, which enables LWS-aware clients to skip the link header discovery, while in auxiliary resource as a role #167 that is not the case.
• The only THEORETICAL difference is that in Define aux & meta in terms of representations #165, the fact that a single URI can potentially return both a primary representation and a link set is clarified terminologically by specifying that the link set is in fact a representation of the resource.