search

ietf-wg-httpapi / deprecation-header

Repository for IETF WG draft deprecation-header
Other
5 stars 5 forks source link

Deprecation link relation type #13

Closed mnot closed 2 years ago

mnot commented 3 years ago

Reading the text, I'm confused, is this linking to information that's about:

  1. a specific deprecation event that's occured
  2. the entire API's policy for deprecation in the future

?

dret commented 3 years ago

On 2021-07-29 08:34, Mark Nottingham wrote:

Reading the text, I'm confused, is this linking to information that's about:

  1. a specific deprecation event that's occured
  2. the entire API's policy for deprecation in the future

the intent was that it can be both. the current text says:

"This can happen before the actual deprecation, to make a deprecation policy discoverable, or after deprecation, when there may be documentation about the deprecation, and possibly documentation of how to manage it."

the goal was to specifically allow both things you listed above. is that unclear, or do you think it should only be one of those two things?

mnot commented 3 years ago

Having a single link relation mean two different things is a bit odd; if someone wants to automate something based upon it, they'll need to have a way of distinguishing them.

dret commented 3 years ago

On Jul 31, 2021, at 06:45, Mark Nottingham @.***> wrote:

Having a single link relation mean two different things is a bit odd; if someone wants to automate something based upon it, they'll need to have a way of distinguishing them.

i'd argue it's one thing: information about deprecation. the nature of it may change depending on whether you look it up before or after depreciation, but it the one place where you'll find deprecation info.

what kind of automation are you expecting? for the status, we have the header field itself. if it's some kind of crawler for deprecation policies, shouldn't that crawler be able to process such a policy for both deprecated and not-yet-deprecated resources?

dret commented 2 years ago

how should we proceed with this one? if we want to provide detailed links to various aspects that may relate to deprecation, we could probably find even more than the two examples given by @mnot above. from the design perspective, the goal was to be able to link to anything that may be useful, but yes, this could be various things. if we want to automate things, wouldn't it be sufficient to base that on the media type of the target of the deprecation link type?

mnot commented 2 years ago

Personally -- I'd hold off creating a link relation type until I had some formats defined that it'd point to, so we could understand the use cases in more detail...

dret commented 2 years ago

On 2022-03-23 21:41, Mark Nottingham wrote:

Personally -- I'd hold off creating a link relation type until I had some formats defined that it'd point to, so we could understand the use cases in more detail...

that's interesting. in my mind, with links and link targets being so nicely different on the web, there's potential in defining the one without the other, as there are always generic formats to fallback to when there are (not yet) specific ones.

but i agree that this is a bit speculative, and that i have no idea if/how for example the "Sunset" link relation is being used. i have recommended for API guidelines to mention it as a way to make information about sunset policies discoverable, but i have no data if/how this is being used.

dret commented 2 years ago

@mnot: since you qualified your last response with "personally", how should be resolve this issue? are you against having such a link relation, or would you be ok with having it without having/defining specific media types for linked resources?

mnot commented 2 years ago

I'm not against it -- I just wonder if it's well-defined enough to be useful as it is.

dret commented 2 years ago

On 2022-03-28 00:05, Mark Nottingham wrote:

I'm not against it -- I just wonder if it's well-defined enough to be useful as it is.

i would argue that it's useful to encourage people to have well-defined deprecation policies and to document them and to make them discoverable. that's something that's independent of specific media types people would use to represent that information. and it's certainly something i am encouraging as part of general API design guidelines, but i have no data on how much people are agreeing with that or already doing it in existing APIs.

dret commented 2 years ago

@mnot, how strongly are you feeling about this? do you want to see changes (the link relation type removed or additional wording about media types for the referenced resource) or are you ok with leaving this as it is?

mnot commented 2 years ago

Re-read and the current text looks sufficient; happy to close.

dret commented 2 years ago

thanks for the feedback, @mnot. closing.