Deprecation link relation type #13
Comments
|
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?
|
|
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. |
|
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?
|
|
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 |
|
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... |
|
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.
|
|
@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? |
|
I'm not against it -- I just wonder if it's well-defined enough to be useful as it is. |
|
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.
|
|
@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? |
|
Re-read and the current text looks sufficient; happy to close. |
|
thanks for the feedback, @mnot. closing. |
Reading the text, I'm confused, is this linking to information that's about:
?
The text was updated successfully, but these errors were encountered: