reconsider re-use of RFC 5829 link relations

[reschke]

These were explicitly defined for version control related relations.

If their semantics are to be relaxed (which might be a good idea), we should revise/update that RFC.

[gabesullice]

I'm wondering what the expected usage of the alternate and successor-version link rels are in this context. In practice, why would a client that is already capable of using the new resource be making a request to the deprecated resource in the first place?

It might be a safer assumption that the client cannot retry its request without causing more problems. If a server really does want to redirect the client to an upgraded resource, perhaps a 3xx status code would be the better mechanism.

If those link relations are meant to convey information about how to upgrade the client, isn't the content of the deprecation resource sufficient? For example, that resource could inform the client's owner that their client should begin following a different link relation in order to avoid visiting the deprecated resource again.

[sdatspun2]

I'm wondering what the expected usage of the alternate and successor-version link rels are in this context. In practice, why would a client that is already capable of using the new resource be making a request to the deprecated resource in the first place?

Case: You are right for a new client. If resource is deprecated after the client has integrated with the deprecated version and gone into production, this header can be used to inform them about the alternate or successor-version.

[gabesullice]

Right, but what do you expect the client in production to do with the link to a successor version? If the production client automatically follows the link, it is likely to break. Therefore, why have the link at all?

[dret]

On 2021-03-28 14:06, Gabe Sullice wrote:

Right, but what do you expect the client in production to do with the link to a successor version? If it automatically follows the link, it is likely to break. Therefore, why have the link at all?

the intention is to make it easier for developers to find out what to do. you can link them to a place that helps them to find out what to do.

i think we have pretty universal consensus that expecting that you can follow a link and that resource is the new resource is not very realistic in most cases. so what we're doing here is trying to find some middle ground between expecting that full automation, or simply saying "this one is not supported/recommended anymore, good luck with finding a replacement."

[gabesullice]

Thanks for clarifying that it is only meant for documentation purposes. The concern raised at the IETF meeting was that naïve clients would try to follow it automatically though and that those semantics are fairly different than the original registration in RFC 5829.

Since you say that "the intention is to make it easier for developers to find out what to do. you can link them to a place that helps them to find out what to do."

It's not clear why the deprecation link relation type doesn't already fill that role. Its semantics appear to match what you just described:

the server can use links with the "deprecation" link relation type to communicate to the client where to find more information about deprecation of the context… the deprecation policy may be available as human-readable documentation or as machine-readable description.

If there's a gap between the definition of deprecation and the intended use of successor-version, then my suggestion is to tweak the definition of deprecation rather than adopt successor-version (and indirectly alter its semantics).

For example, we could add text like "It is RECOMMENDED that the target resource provides a link to a resource which affords the same capabilities as the deprecated resource."

If we really want to provide link relation types to reference the new resource, we could recommend that the deprecation resource use about to reference the deprecated resource and its replacement. This would be semantically correct and would make it difficult to programmatically follow the link, which I think would be good to discourage.

[dret]

thanks everybody for chiming in. i think i am reconsidering our choice and it might indeed be sufficient to simply rely on the deprecation link relation for linking to documentation. @sdatgit @sdatspun2 , is it ok for you if we resolve things that way?

[sdatspun2]

@gabesullice I am not sure how much naive-proof we should make this header :) As @dret mentioned, the link relations are for information purposes only, it is not required to use successor-version if API publisher does not want to. We can clarify this aspect but just because someone naive may start using it if seen and therefore it should not be in this spec is not a very convincing argument.

[darrelmiller]

We have a use case where intermediaries and log crawlers are going to identify uses of deprecated resources and notify API consumers that they should take action to update their client code. Using a link relation as a signal is a considerably higher bar than detecting the presence of a header name. Especially considering how "interesting" it is to parse link headers. I would prefer there to be a simple deprecation header with a link relation in addition to discover more.

[dret]

On 2021-07-06 15:45, Darrel wrote:

We have a use case where intermediaries and log crawlers are going to identify uses of deprecated resources and notify API consumers that they should take action to update their client code. Using a link relation as a signal is a considerably higher bar than detecting the presence of a header name. Especially considering how "interesting" it is to parse link headers. I would prefer there to be a simple deprecation header with a link relation in addition to discover more.

that one i don't fully understand. it is a really nice used case, but isn't that covered by building tooling to look for the header field and you're done? the header field is still the signal, the link relation simply is some additional info that may go with it.

[sdatspun2]

I would prefer there to be a simple deprecation header with a link relation in addition to discover more.

Are you looking for something like the following for example?

Deprecation: Sun, 11 Nov 2018 23:59:59 GMT; link="https://api.example.com/v2/customers"; rel="successor-version"

I agree with @dret that tooling could be used instead with the existing syntax.

[dret]

@darrelmiller, are you looking for what @sdatspun2 suggested (i.e., the addition of linking capabilities to the Deprecation header field)? if not, could you please clarify? thanks!

[darrelmiller]

@sdatspun2 @dret Feel free to ignore my comment. I didn't read close enough. I thought there was a suggestion to only have the link relation and not have the deprecation header.

[sdatspun2]

@darrelmiller Will you be ok to close this issue then?

[dret]

reading the last comments as this being ok to be closed, and closing it.