proposed example: redirect to new location

[reschke]

Maybe a good example would be a redirect to a different site, with "Deprecation" saying when the redirecting site is going to disappear.

[sdatspun2]

Consider a post-production cases where client is using a version of resource that is now deprecated. Resource provider cannot make the choice for clients. Resource provider can inform the clients via this header about the choices available in case of deprecation. Let me know if I am missing something.

[dret]

i tend to agree with @sdatspun2 here: deprecation is something different from redirection. in some cases there may be a redirect in place, but that's not necessarily the case.

[dret]

any thoughts on this, @reschke? we discussed a lot more and still think that we should avoid overloading deprecation, both in the spec and in examples. what "deprecation" means is not something that we want to standardize, we simply want to allow resources to signal that they are deprecated (and it then requires additional information about the resource or the API to understand if/what something can be done about it programmatically).

[darrelmiller]

@dret I'm not sure I understand why @reschke 's example wouldn't be helpful for readers. Using the deprecation header to signal that resource A is going to be deprecated and in the future a client will not be able to use resource A to redirect to resource B, seems like a valid use case. In the case of a permanent redirect, a deprecation header seems like a good signal to give to clients to update any locally stored URLs.
Are you concerned that a finite set of examples would make readers believe there a limited set of scenarios where deprecation is appropriate?

[sdatspun2]

I agree with @dret, we should avoid overloading the retype deprecation with redirect. However, would it help to overload just the reltype successor-version with redirect? See https://github.com/ietf-wg-httpapi/deprecation-header/blob/main/draft-ietf-httpapi-deprecation-header.md#recommend-replacement.

dret commented 15 days ago
any thoughts on this, @reschke? we discussed a not more and still think that we should avoid overloading deprecation, both in the spec and in examples.

reschke commented on Mar 12
Maybe a good example would be a redirect to a different site, with "Deprecation" saying when the redirecting site is going to disappear.

[reschke]

I agree with @dret, we should avoid overloading the retype deprecation with redirect.

That's not what this is about.

But are you disagreeing that one can use that field on a redirect?

[sdatspun2]

@reschke Can you give example in the form of response? Perhaps you are saying that redirect with normal HTTP machinery but add Deprecation header too.

[reschke]

What I'm trying to say is that it seems natural to augment a redirect response with a deprecation header field.

For instance:

301 Permanent Redirect HTTP/1.1
Location: /foo
Sunset: ...

would convey that the resource already redirects, but that the redirector will be taken out of service at a concrete time in the future.

[sdatspun2]

@reschke You mean deprecation, right? Makes sense for non-HTTP API applications indeed.

301 Permanent Redirect HTTP/1.1
Location: /foo
Deprecation: ...

[reschke]

I think both deprecation and sunset could be applicable.

[dret]

On Aug 25, 2021, at 09:04, Julian Reschke ***@***.***> wrote: I think both deprecation and sunset could be applicable.

fwiw, sunset has been published as a separate RFC for a while, and at least for now, no update is planned. for the deprecation draft, we probably should just use the deprecation header field in examples.

[darrelmiller]

@sdatspun2 Can I ask why you qualified your support for the example with "for non-HTTP API". I do believe there are many HTTP API implementations that return redirects. Making a caller aware that the initial resource is going away seems like a viable scenario.

[sdatspun2]

@darrelmiller We have defined different and explicit rels for guiding the consumers of the API, see https://github.com/ietf-wg-httpapi/deprecation-header/blob/main/draft-ietf-httpapi-deprecation-header.md#recommend-replacement. In which case, the API publisher would redirect? How should the default behavior be specified by the API publisher?

[dret]

i m still a bit hesitant to venture too far into "and here are all the things that could be done" land, since this is an area where it seems we can expand on examples indefinitely. maybe i am a bit scarred by my recent linkset experience. my preference would be to not add examples when we can, but only when we have to.

[dret]

sorry for reviving this, @reschke, but since this is unresolved i'd like to re-open the discussion. my vote still goes to "do we need such an example" over "can we add such an example", and i don't think we need such an example. how strongly do you feel about having such an example in the spec?

[reschke]

AFAIR, I thought this would be a good example. I'll have to re-read the spec to see what examples it currently has, and whether they are better. That might take some time.

[dret]

please let us know what your conclusion is, @reschke. just repeating myself here: please don't just think about whether it's a good example, but whether it's a necessary example. thanks!

[dret]

@reschke, i am doing a bit of housekeeping and noticed that this issue is still open. can you please have a quick look and see whether such an example in your opinion is needed? thanks!

[reschke]

Noted. Will re-read over the weekend.

[reschke]

Ok.

1. Looked at the existing examples. These are confusing, because there are two, and the second essentially is a superset of the first. Things would be less confusing if this was streamlined.

2. Are the examples sufficient? Maybe. I think it would be good if the examples should actual request/response pairs, instead of just repeating syntax defined earlier on. But it's an editorial choice.

[sdatspun2]

@reschke should we close this?

[richsalz]

ping @reschke , @sdatspun2 to decide by end of WGLC to add another example, or close this.