recommend HTTP status codes

[dret]

if Deprecation is used, what HTTP status code should be used? i think it would be good to say something about this. i guess that continuing to use the same ones is ok, since the resources are still operational. but some people might want to use 301 or similar status codes.

[dret]

or looked at it from the other side of things: when do you even have to use Deprecation instead of simply using 301? the more clearly the spec describes these decisions, the easier it will be for developers to use the header as intended and consistently.

[sdatgit]

Since resources are operational, I would think they should continue to use what they use otherwise there client apps are affected. We should clarify this if necessary.

[dret]

On Apr 19, 2019, at 07:45, Sanjay Dalal notifications@github.com wrote:

Since resources are operational, I would think they should continue to use what they use otherwise there client apps are affected.

that sounds reasonable to me, but it still might be helpful to add a section on "resource behavior" or something along those lines that talk about this. i think this kind of "what do i do as a developer" guidance can help people to more easily use the spec. what do you think?

[sdatspun2]

The meaning of deprecation is that that the resource should be operational but we can add section that provides guidance. Does not harm. In fact, I notice that we have started introduction as such only. Here is repeat in new section. If you agree, I will commit with other changes.

Resource Behavior

As mentioned in the introduction, deprecation is a technique to communicate information about the lifecycle of a resource. Its purpose is to encourage applications to migrate away from the resource, to discourage the applications from forming new dependencies on the resource, and to inform the applications about the risk of continuing dependence upon the resource. The act of deprecation MUST NOT change any behavior of the resource.

[dret]

On 2019-05-09 12:44, Sanjay Dalal wrote:

The meaning of deprecation is that that the resource should be operational but we can add section that provides guidance. Does not harm.

thanks, looking good.

just nitpicking: the resource behavior is changed since the resource starts advertising its own deprecation, but of course you're right about the spirit of this.

but the resource could change behavior in other ways as well, such as linking to a new version or similar kinds of things, right?

[sdatspun2]

Instead of

The act of gdeprecation MUST NOT change any behavior of the resource.

...how about this?

Resource owner MUST NOT enhance the deprecated resource with new features and functionality. The resource could still be made more reliable, available, secure, performant, etc.

[dret]

On 2019-05-14 15:58, Sanjay Dalal wrote:

Resource owner MUST NOT enhance the deprecated resource with new features and functionality. The resource could still be made more reliable, available, secure, performant, etc.

i don't think there is a need for this to be normative. i'd just recommend for the resource to not change behavior drastically:

Deprecated resources SHOULD keep functioning as before, allowing consumers to still use the resources in the same way as they did before the resources were declared deprecated.

[ioggstream]

The interesting discussion on whether deprecation headers affect the underlying resource does not reflect the issue title.

Those headers are informative, and must be totally decoupled by the resource status codes;

i don't think there is a need for this to be normative.

agree, this may create some complexities in the adoption.