sdatspun2 / deprecation-header Goto Github PK

in most cases, people have their draft repos as public so that anybody can look at the current draft and the history. limiting push access makes sense, but my vote is to make this repo public.

Wish

If you are interested in setting up a CI for publishing on gh-pages, you can reuse the code
from this repo.

• https://github.com/ioggstream/draft-polli-resource-digests-http

If you are interested, I can provide a PR - though you should configure your circleci account
to make the build.

There are cases when there are multiple API deprecations happening at a different time. Business policies could change at any point of time requesting certain API elements to be deprecated. So, there should be a way to indicate this in the header. Otherwise, developers are not going to be alerted to read API documentation to understand new deprecations and to plan their integration changes accordingly.

I expect

The date format MUST be the IMF-fixdate syntax for the HTTP-date

see https://tools.ietf.org/html/rfc7231#section-7.1.1.1

Instead

It uses HTTP-date, which includes support for obs-date

HTTP-date = IMF-fixdate / obs-date

iiuc rfc7231 § 7.1.1.1 contains a discussion on the subject which should be repeated here if we don't forbid obs-date

having the <date or version> model for the since part seems to be problematic, in particular since a version identifier may be a date?
it seems simpler to make sure that the deprecation always has to be announced by a date, so that clients know what to count on. and since the date can be in the past or in the future (at least that's my mental model so far), what about instead of saying since, just using the date in the same way as it is done for the Sunset header field? that would also make both fields nicely parallel in their design.

Is there a need to provide limited amount of arbitrary text in Deprecation header? As an example, take a look at the attached response for an Ajax call using sync property which is deprecated.

we have decided to leave deprecation of individual features of an API's payload as out of scope, which i still think is a good decision.
but what about adding a section that says that while we're not supporting deprecation at a finer granularity, the deprecation link relation could still be used to link to documentation? we could say that while defining a mechanism to identify deprecated parts of a message is out of scope, for anybody doing this it would be ok and potentially helpful to use the deprecation link relation to make it easier to find information about the deprecation policy and state.

Suggestion

HTTP WG is working on - Structured Headers

We could consider using a structured header for Deprecated, eg to provide the ability to evolve it in time.

Notes

HTTP WG is working on an interesting set of extensions:

• https://github.com/httpwg/http-extensions

which includes:

• writing HTTP-based APIs BCP
• Structured Headers

i may be wrong, but i am pretty sure that the convention is to name individual drafts with one author name, following the draft-... pattern.
brief check at https://www.ietf.org/standards/ids/guidelines/ and indeed: "A string related to the name of one of the authors in some way. There are no mechanical rules for this string but objectionable or misleading strings are subject to change or removal at the discretion of the Secretariat."

i am wondering about this paragraph:

Servers SHOULD NOT include more than one Deprecation header field in the same response. If a server sends multiple responses containing Deprecation headers concurrently to the user agent (e.g., when communicating with the user agent over multiple sockets), these responses create a "race condition" that can lead to unpredictable behavior.

the first sentence seems to talk about sending more than one header field in the same HTTP message. the second sentence seems to talk about multiple HTTP messages? i am not sure we want to go to this level of detail. if we do, we'd have to describe the race condition, and i am not even sure that we have one here. anyway, i'd probably drop that one completely.

should we have some kind of sunset parameter for the Deprecation header field, or instead refer to the Sunset HTTP header field and recommend to use that one when deprecation information is augmented with sunset information? my vote is for reusing the Sunset header field.

I expect

That when using Sunset and Deprecation, their value:

• MUST be consistent;
• this should be normative.

I was speaking to an API developer regarding the deprecation header. He suggested having scope would help. Scope could be request, response or endpoint. Documenting the ask in this issue.

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.

given the current ABNF, it seems like a version parameter must occur before a date parameter, if both are used. that's probably not intentional, and should be changed to allow either sequence (and probably extensions should be allowed to be mixed in as well).

Informative note

I just wanted to report the usage of Warning header for signaling deprecation of resources.

The implemented solution provides some flexibility for messages:

Warning: 299 - "The parameter {name} is deprecated and will be removed by {date}.
Please see {link} for details." "Wed, 21 Oct 2015 07:28:00 GMT"

https://opensource.zalando.com/restful-api-guidelines/#189

I wish

an example response for deprecating query parameters or method

Note

iiuc as of now, only a resource-target deprecation is shown.

currently, the security considerations talk about the Link header field. is that because of a copy/paste from that spec, or because they are supposed to talk the link relation and how that is going to be used in a Link header field? either way, this section needs some clarification.

getting back to the draft i am still not quite sure about the way the version mechanism works. it seems to assume that there is a well-known (but opaque) version identifier that clients know and can use? how would they know it, and what would they use it for? would it be possible that various versions can show up as deprecated at the same URI?
if you could try to write a little more about how the version identifier is assigned, how clients learn about it, what kind of actions they are supposed to take when it shows up in a deprecation header field, that would be great. it might also help others to better understand the mechanism.

I'd include a brief message about the deprecation in this header. This anyways is intended to be logged or presented to a human user. Deprecation is some sort of a warning that deserves to have first-class citizen treatment and that's why there is a proposal to introduce a new header.