Deprecation scope - Githubissues

darrelmiller commented 3 years ago

The introduction to this RFC says:

The HTTP Deprecation Response Header Field can be used to signal to consumers of a URI-identified resource that the resource has been deprecated.

However later in the documentation section it says:

For a resource, deprecation could involve one or more parts of request, response or both.

These two statements do not seem consistent. My understanding of the term "resource has been deprecated" is that it will no longer respond with a 2XX to any HTTP method. Is that understanding incorrect?

Perhaps the initial paragraph could be changed to say,

The HTTP Deprecation Response Header Field can be used to signal to consumers of a URI-identified resource that one or more parts of resource has been deprecated.

dret commented 3 years ago

On 2021-03-21 00:02, Darrel wrote:

The introduction to this RFC says:

The HTTP Deprecation Response Header Field can be used to signal to
consumers of a URI-identified resource that the resource has been
deprecated.

However later in the documentation section it says:

For a resource, deprecation could involve one or more parts of
request, response or both.

good catch, thanks. we did make the decision to only support deprecation at the resource level, so this sentence may be a left-over from the previous language that claimed a more fine-grained facility, without ever providing a model for it.

this sentence should be removed.

These two statements do not seem consistent. My understanding of the term "resource has been deprecated" is that it will no longer respond with a 2XX to any HTTP method. Is that understanding incorrect?

that's not what deprecation is for this draft (but that's what sunsetting can be). deprecation simply means it's no longer the recommended resource to use, and that maybe there's a replacement somewhere, but that for the time being it's still usable.

"In several fields, deprecation is the discouragement of use of some terminology, feature, design, or practice, typically because it has been superseded or is no longer considered efficient or safe, without completely removing it or prohibiting its use. Typically, deprecated materials are not completely removed to ensure legacy compatibility or back up practice in case new methods are not functional in an odd scenario."

https://en.wikipedia.org/wiki/Deprecation

Perhaps the initial paragraph could be changed to say,

The HTTP Deprecation Response Header Field can be used to signal to
consumers of a URI-identified resource that one or more parts of
resource has been deprecated.

thanks for the suggestion, but the better edit is the other way round: removing the language that hints at a deprecation model more fine-grained than at the resource level.

darrelmiller commented 3 years ago

Consistency is good. I am disappointed that we are heading in the direction of entire resource deprecation only, but I'm biased because we in Microsoft Graph are already using it for partial deprecation.

dret commented 3 years ago

On 2021-05-01 03:52, Darrel wrote:

Consistency is good. I am disappointed that we are heading in the direction of entire resource deprecation only, but I'm biased because we in Microsoft Graph are already using it for partial deprecation.

without knowing anything about it, i am assuming that the way you identify deprecated features is specific to your API. is that correct?

i think the problem we face is that any model supporting partial deprecation would need to provide a way how to identify those features, otherwise it would be relatively pointless. that's tricky to do when all the current draft assumes is that your API is HTTP-based.

mikepizzo commented 3 years ago

without knowing anything about it, i am assuming that the way you identify deprecated features is specific to your API. is that correct?

Yes; Microsoft Graph has a way to describe the resources returned by its API, including whether individual members of the resources are deprecated.

i think the problem we face is that any model supporting partial deprecation would need to provide a way how to identify those features, otherwise it would be relatively pointless. that's tricky to do when all the current draft assumes is that your API is HTTP-based.

It seems like Darrel's suggestion would provide wiggle-room for services (like Microsoft Graph) that do have a separate mechanism for describing parts of a resource that are deprecated.

Given that we already have response headers for both deprecation and sunset (which some users find confusing), I'd really hate to introduce a 3rd response header for "partial-deprecation".

sdatspun2 commented 3 years ago

Microsoft Graph has a way to describe the resources returned by its API, including whether individual members of the resources are deprecated.

@darrelmiller @mikepizzo Can you provide a reference where it shows an example of deprecation of individual members. Originally, we were thinking that the header could point to API reference which if generated from an OAI doc would leverage OAI's deprecated flag to identify individual members of the deprecated resource.

dret commented 3 years ago

if you have a partial deprecation model, @darrelmiller & @mikepizzo, would you say the entire resource is deprecated as a result of one part being deprecated? if yes, then maybe adding a "and here's more info for those APIs that have partial deprecation models" part makes sense. if not, then it seems that the partial deprecation info can be left entirely to whatever model the API has. would you agree?

mikepizzo commented 3 years ago

@dret -- No, it's important to our API versioning that deprecating one part of the resource does not deprecate the entire resource.

@sdatspun2 -- Our API represents a graph of resources. Resources have defined properties, and we want the ability to mark a property as deprecated in favor of a new property.

For example, we have an educationSubmission resource type that has properties such as recipient, status, and so forth. It also has properties "releasedBy" and "releasedDateTime" that we want to mark as deprecated.

While you can select an entire resource, in our API you're encouraged to use query options to select only the subset of properties you actually need from the resource. If you do the later, you should only be alerted if you specifically select "releasedBy" and "releasedDateTime".

We do have a way to document that a resource, or property of a resource, has been deprecated, and I'm sure we will use the deprecated flag in our OAI description if we don't already.

Does that help?

dret commented 3 years ago

@mikepizzo: if you say the resource itself does not get deprecated, is there anything speaking against just relying on the API mechanisms of deprecating some parts of it? why would you need a signal in addition to that, what would that be used for?

mikepizzo commented 3 years ago

@dret -- We use the deprecation header to alert the application that the request that they made contained deprecated content. The app could then, for example, pop up a dialog to the user saying that this version of the app is referencing deprecated content and to please check if there is a newer version of the app available.

dret commented 3 years ago

now i am a bit confused, @mikepizzo. the way the draft is currently phrased it is used to signal an API consumer that the resource is deprecated. what you're writing there seems to be rather different, i read it as using the header field not to make statement about the resource, but to make a statement about the request. is that correct? if so, then given the current definition of the header field, you're not communicating what you're intending to communicate.

dret commented 3 years ago

returning to the original discussion: partial deprecation. currently the idea is that the header field signals that a resource is deprecated, meaning that when it is present, the resource is deprecated. here are some points worth discussing:

if there is a concept of partial deprecation that would probably imply that the resource is only deprecated when the header field is present and there is no indication of a partial deprecation.
we seem to agree that partial deprecation is hard to generically describe, leaving it up to each API to define its own model of partial deprecation. if that's the case, then what is gained by also signalling partial deprecation in the header field, instead of just relying on whatever mechanism the API has to provide anyway?

dret commented 3 years ago

FYI: #8 seems related but it's "about scope in the other direction", by which i mean that instead of allowing a scope smaller that the resource, it talks about a scope larger than the resource.

darrelmiller commented 3 years ago

@dret Using strict interpretation of HTTP resources and representations, it does make sense to me to associate the Deprecation header to the resource in its entirety. Trying to describe the evolution of the representation seems like a distinct problem. Unfortunately, the reality of API implementations in the wild is there is frequently a tight coupling between resource identifier and representation design.

If an API were to use the Deprecation header to signal that this "version" of the resource is being deprecated due to a change in the representation, would that be considered an acceptable use case? My interpretation of deprecating a resource doesn't preclude an API from bringing back a new "version" of that resource in the future.

Does this seem like a reasonable "misuse" of the header?

dret commented 3 years ago

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

@dret https://github.com/dret Using strict interpretation of HTTP resources and representations, it does make sense to me to associate the Deprecation header to the resource in its entirety. Trying to describe the evolution of the representation seems like a distinct problem.

so it seems we're on the same page here. it could be useful to describe the evolution, but that seems like a hard problem to solve in a generic way so that it would be useful to expose at the HTTP level.

Unfortunately, the reality of API implementations in the wild is there is frequently a tight coupling between resource identifier and representation design.

sometimes there is. but oftentimes these resources evolve (and/or their representations do), but that's just a different concern from signaling the deprecation of the resource itself.

If an API were to use the Deprecation header to signal that this "version" of the resource is being deprecated due to a change in the representation, would that be considered an acceptable use case? My interpretation of deprecating a resource doesn't preclude an API from bringing back a new "version" of that resource in the future. Does this seem like a reasonable "misuse" of the header?

this is interesting because just recently somebody reached out and asked whether it would be ok to deprecate specific representations, let's say you're serving XML and JSON (using conneg) and will stop serving XML.

in my mind, both your use case and that one are not covered by the current spec. it would require an additional mechanism in the spec to support this use case, so that you can always differentiate between "this representation type/design is deprecated" and "this resource is deprecated".

i am also not sure that this idea of "deprecating fields" should be covered by the same mechanism (as our current "this resource is going away, you might want to deal with that" approach). it is more about supporting schema evolution and evolving the data model, and deprecating a field is just one aspect of this general space.

dret commented 3 years ago

we're trying to reduce the list of open issues. @darrelmiller and @mikepizzo, what is your takeaway from this discussion? my next step would be to change the spec to be more clear that we do not support a model for partial deprecation, and that deprecation always applies at the resource level. is that a resolution you could live with? if not, how else can we address this issue?

darrelmiller commented 3 years ago

Personally, I think it would be unfortunate to spend the time to bring this header through the whole process and not provide any support for signaling that some part of a resource has been deprecated. My experience has been that fine grained deprecations are far more common in an API that complete resource deprecation. However, mine is only one opinion and I don't think this being an open issue should block us from moving forward with the call for adoption. I think that will allow us to get more input into this topic.

This issue has some similarities to the challenges we are running into with the content-warning. where that header is signaling that somewhere in the payload there is a warning. Perhaps the solution is to have a companion Content-Deprecation header. Maybe that does warrant a different specification, but it is worth a conversation.

dret commented 2 years ago

any updates on this one, @darrelmiller? keeping in line with Sunset it seems that Deprecation should behave similarly, i.e. (at least by default) making a statement about the resource. if you're proposing something in addition, then the desired semantics for you seem to be "the resource is not deprecated, but parts of the model are". if that's true, then that's something we're not covering currently, and if you'd like to see it covered, we need to start somewhere. the Content-Deprecation header field idea doesn't sound too far-fetched to me, and i like the fact that it is indeed a separate thing, and not mixed into the simpler resource-level model.

sdatspun2 commented 2 years ago

At IETF-112, we agreed to not go into resource's representation. @darrelmiller should we close this issue?

darrelmiller commented 2 years ago

Yes,

dret commented 2 years ago

It feels like there still is some language in the draft referring to the idea of deprecation being "below" the resource level, specifically in the section about documentation.

dret commented 2 years ago

Closing with a new set of edits.

ietf-wg-httpapi / deprecation-header

Deprecation scope #7