linkset payload in HTTP header

[hvdsomp]

I am not so sure anymore why we decided it was a good idea to allow providing a linkset payload as the content of the Link header of the link set resource:

• It can only be done for linksets formatted according to the application/linkset format, not for the application/linkset+json format.
• It seems to go against a major motivation for introducing link sets, i.e. HTTP headers can become too large when many links need to be provided.
• It requires clients to go look in two places to find linkset payloads: in the header and the body of the linkset resource.

Would it not be more elegant to provide linkset payloads only as the body of the link set resource?

[dret]

On 2019-08-01 03:33, Herbert Van de Sompel wrote:

I am not so sure anymore why we decided it was a good idea to allow providing a linkset payload as the content of the |Link| header of the link set resource:

i am a bit confused, what do you mean by this? isn't by definition every link header a linkset? wasn't that the goal of our undertaking?

or is it the confusion of having links about links? that is confusing, but that's not something we control. we cannot disallow headers fields being used for our media types.

• It can only be done for linksets formatted according to the |application/linkset| format, not for the |application/linkset+json| format.

because that's how we define the application/linkset media type, right?

• It seems to go against a major motivation for introducing link sets, i.e. HTTP headers can become too large when many links need to be provided.

the links in a link header served for a linkset resource could be very different ones, right? they could be metadata about the linkset resource, whereas the linkset resource could be, for example, an archived linkset from/for a different resource altogether.

• It requires clients to go look in two places to find linkset payloads: in the header and the body of the linkset resource.

every HTTP interaction can have a link header field. there's nothing we can do about this.

Would it not be more elegant to provide linkset payloads only as the body of the link set resource?

sure. our media types by definition only can used as entities in HTTP interactions. but we have no control over what kind of headers are being used in these interactions.

[hvdsomp]

I thought that the media types we are defining are for documents that can be obtained by issuing an HTTP GET on a link set resource. The media type of these documents is then revealed in the Content-Type header of the HTTP response.

I did not realize we were also defining a media type for the content of a Link header, when that content is provided in a Link header. Actually, AFAIK, the notion of media type does not exist for the content of any HTTP header. But, I could be wrong, of course.

I find it totally normal that a link set resource provides a response body compliant with the two media types we define. A client can glance which media type is provided by the link set resource from the Content-Type header of the response. What I find less intuitive is that a link set resource can also deliver its set of links pertaining to the origin resource in its own Link header. That’s not to say the link set resource can not have a Link header. Obviously, it can but one would expect it to contain links pertaining to itself. Like regular Link headers do.

Let’s consider this from the perspective of a client who accesses the origin resource. The client finds a “linkset” link pointing at a link set resource. The “linkset” link can have a “type” attribute indicating which media type the client can expect when accessing that link set resource. So, that would be application/linkset or application/linkset+json in case the set of links are provided in the body of the response. If any other media type is used as the value of “type”, the client deduces the set of links are not in the body, but elsewhere, ie in the Link header. Now, that Link header is just a Link header, it does not comply to any of the media types we define because media types don’t apply to HTTP headers (I think). Meaning the constraints that we intend to apply via our format definitions (throw relative URIs away OR provide absolute URIs) don’t apply. Meaning the link set resource does not have to abide by these constraints. Meaning the client sees relative URIs, does not throw them away, and misinterprets them.

On Aug 1, 2019, at 17:59, Erik Wilde notifications@github.com wrote:

On 2019-08-01 03:33, Herbert Van de Sompel wrote:

I am not so sure anymore why we decided it was a good idea to allow providing a linkset payload as the content of the |Link| header of the link set resource:

i am a bit confused, what do you mean by this? isn't by definition every link header a linkset? wasn't that the goal of our undertaking?

or is it the confusion of having links about links? that is confusing, but that's not something we control. we cannot disallow headers fields being used for our media types.

• It can only be done for linksets formatted according to the |application/linkset| format, not for the |application/linkset+json| format.

because that's how we define the application/linkset media type, right?

• It seems to go against a major motivation for introducing link sets, i.e. HTTP headers can become too large when many links need to be provided.

the links in a link header served for a linkset resource could be very different ones, right? they could be metadata about the linkset resource, whereas the linkset resource could be, for example, an archived linkset from/for a different resource altogether.

• It requires clients to go look in two places to find linkset payloads: in the header and the body of the linkset resource.

every HTTP interaction can have a link header field. there's nothing we can do about this.

Would it not be more elegant to provide linkset payloads only as the body of the link set resource?

sure. our media types by definition only can used as entities in HTTP interactions. but we have no control over what kind of headers are being used in these interactions. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub, or mute the thread.

[dret]

On 2019-08-01 10:18, Herbert Van de Sompel wrote:

I thought that the media types we are defining are for documents that can be obtained by issuing an HTTP GET on a link set resource. The media type of these documents is then revealed in the Content-Type header of the HTTP response.

that's how media types are defined and used, right?

I did not realize we were also defining a media type for the content of a Link header, when that content is provided in a Link header. Actually, AFAIK, the notion of media type does not exist for the content of any HTTP header. But, I could be wrong, of course.

there is no media type for header fields. but there was the idea that we'd like to be able to use link header field content outside of the context of the header, and have a media type for labeling it. at least the current draft still makes that explicit in a number of places.

I find it totally normal that a link set resource provides a response body compliant with the two media types we define. A client can glance which media type is provided by the link set resource from the Content-Type header of the response. What I find less intuitive is that a link set resource can also deliver its set of links pertaining to the origin resource in its own Link header. That’s not to say the link set resource can not have a Link header. Obviously, it can but one would expect it to contain links pertaining to itself. Like regular Link headers do.

our media type will do whatever we end up defining for it. link header fields do what they do without us having any say over what they can and cannot do, with links delivered in them not being constrained or changed by the media type of the entity they are delivering.

Let’s consider this from the perspective of a client who accesses the origin resource. The client finds a “linkset” link pointing at a link set resource. The “linkset” link can have a “type” attribute indicating which media type the client can expect when accessing that link set resource. So, that would be application/linkset or application/linkset+json in case the set of links are provided in the body of the response.

yes.

If any other media type is used as the value of “type”, the client deduces the set of links are not in the body, but elsewhere, ie in the Link header.

no. it could be a different type of "linkset" as well.

Now, that Link header is just a Link header, it does not comply to any of the media types we define because media types don’t apply to HTTP headers (I think).

yes.

Meaning the constraints that we intend to apply via our format definitions (throw relative URIs away OR provide absolute URIs) don’t apply. Meaning the link set resource does not have to abide by these constraints. Meaning the client sees relative URIs, does not throw them away, and misinterprets them.

no. HTTP is stateless. if you GET a linkset (regardless of how you learned about its URI), you follow the rules. if you find relative links if the link header, they mean what they always mean: they apply to the URI of the GET request (we have no powers to change that). if the server wants to serve links about the resource that linked to the linkset (sorry about that wording), then it needs to provide these links as absolute links, regardless of whether they are served in the link header or in the linkset entity body.

[dret]

done.