fmvilas commented 4 years ago

It would be great to have a way to flag that a channel is deprecated or is going to disappear/sunset at some point. We already thought about a property like deprecated: true but that would be insufficient if we want to understand when the channel is going to finally disappear and what alternatives do I have.

I thought on something like this, following a bit the idea behind the sunset header definition for HTTP by @dret.

deprecated: true
sunset:
  datetime: 2020-01-21T18:33:19Z # Optional
  message: Stop using it now! # Optional
  externalDocs: myjira.com/issue-7 # Optional (Thanks Michael Davis)
  alternativeChannel: /alternative/channel/name # Optional

I'm sure some folks over at JSON Schema and OpenAPI already had this discussion. Any thoughts? @philsturgeon @MikeRalphson @relequestual

Source of discussion here: https://asyncapi.slack.com/archives/C34F2JV0U/p1579542224002900

philsturgeon commented 4 years ago

There's also the Deprecation header from the same author. https://tools.ietf.org/html/draft-dalal-deprecation-header-02

Although a group effort like anything in these projects, I was tasked with figuring out how we'd do deprecation in JSON Schema 2019-09, and settled for deprecated: true. This was mostly to match OpenAPI and not introduce more divergence, but there was a lot of other thinking behind it.

When Which How Version

Whenever the conversation came up, it started as: "Let's just have a boolean!"

deprecated: true

Then it was "we also need a reason"

deprecated: "We removed this endpoint, use some other endpoint"

Then the conversation would branch and some people would start trying to figure out how to describe the endpoint (in your case channel, or for JSON Schema a property).

deprecated: 
  message: "We are getting rid of the foo channel because it's replaced with bar"
  channel: bar

Others would care less about that and move into "we also need to know when it will be deprecated, the actual date" then somebody else argues versions are better, and the people involved decide that the best solution is both:

```yaml
deprecatedSince: 2020-01-01
deprecatedAt: 2020-02-01
deprecatedVersionSince: v1.5
deprecatedVersionForRemoval: v2.0

Design Time vs Runtime

Ugh. I didn't see a single one of these conversations go well, and in the end I figured: look, we can use deprecated: true as a hint that this thing is likely not long for this world, then they can look at the HTTP message to see if there is a Deprecation or Sunset to get the rest of the information.

Afterall, it is easy for me to write up a description document that says "this thing is going in two months" but oh dammit some million dollar client hit a roadblock and they're gonna need it for another month.

Or, the plan was to make it last another year then we found an issue that made us want to ramp that up, 80% of clients are off it, so lets push that date forward a little.

Unless everyone involved is very much entirely on top of their sh*t, the chances of a prediction being entirely correct and never needing to change is... low. As such I'd rather emit all the specifics at runtime, instead of shoving it into descriptions which could be distributed and not updated for a while.

tldr: IHMO deprecated: true is fine. 👍

dret commented 4 years ago

On 2020-01-23 12:14, Phil Sturgeon wrote:

There's also the Deprecation header from the same author. https://tools.ietf.org/html/draft-dalal-deprecation-header-02

i was going to point to that one. thanks, phil.

Whenever the conversation came up, it started as: "Let's just have a boolean!"

deprecated:true

so, our thinking was to say "at the very least, you want to able to signal upcoming deprecations", so we added a date. we make it very clear that this is a hint and not a promise or threat: the actual date might change. but once it is in the past, the API clearly is in "it was deprecated back then" state.

and then we stopped branching into scenarios because it seemed like they were quickly diverging into a complex universe of machine- and human-targeted ideas.

derberg commented 4 years ago

Back in days I worked for a few years on a platform for publishing microservices, we had marketplace and all that stuff so you can imagine we had hundreds of different APIs and we used RAML. The pain was exactly when we new we have to deprecate something. We ended up with writing information manually in release notes, and we had a plan to invent a kind of notification system where we would put proper data about deprecation in a machine-readable format. If we would already have all of those in a specification writing such notification center would be much better as we already had all those services in a system and they all were exposing RAML files on the root of the service.

My suggestion is:

deprecated:
  sunset: 2020-01-21T18:33:19Z # Optional 
  reason: Stop using it now! # Required
  externalDocs: myjira.com/issue-7 # Optional (Thanks Michael Davis)

deprecated: # not boolean but an object, if it is there in the spec for me it is like true
sunset: this is how we called the closing of the above-mentioned platform :) and it is also a word that has a bit positive "sound". This would be date fields like in the HTTP header proposal
reason: I like it more than a "message" or a "description". I took it from https://www.apollographql.com/docs/graphql-tools/schema-directives/. This would be required field
externalDocs: great suggestion by Michael, I would use it in the above described use case as a field where I provide a link to release notes with more details and migration instruction
alternativeChannel: this is a detail that should be in release notes, or in a reason if someone is too lazy. I can't imagine what I can use this field for programmatically. I would not automatically switch to a new channel, deprecations are things that need closer manual attention.

rv0 commented 4 years ago

I like where this is heading and the idea of all the extra properties is very good and we would most definitely use a lot of the optional ones..

The sunset property can be confusing though, especially for people that are not native english speakers. (I always found it a confusing word myself). I would use a more descriptive property like for example "endDate", "purgeDate", "removalDate", ...

Externaldocs as plural suggests an array payload instead of string

MikeRalphson commented 4 years ago

@fmvilas sorry I never replied to the above, must have missed it. I believe these are the currently open related OAS issues:

Relequestual commented 2 years ago

I don't believe we've looked to address this in JSON Schema. It would be nice to have it uniformly across API specs and JSON Schema. I'm open to anything we can get agreement on which is useful. As @dret noted, there are some existing draft standards for this. @philsturgeon wrote an article which links to both and has some good points for discussion: https://blog.stoplight.io/deprecating-api-endpoints

dret commented 2 years ago

On 2021-11-08 12:00, Ben Hutton wrote:

I don't believe we've looked to address this in JSON Schema. It would be nice to have it uniformly across API specs and JSON Schema.

that would be interesting but challenging. currently, deprecation/sunset work at the resource level, so at a granularity level that to some extent is "above" JSON schema.

I'm open to anything we can get agreement on which is useful.

same here. these are extremely standard things to do in pretty much any API out there, so any support we can provide would be useful for pretty much everybody.

smoya commented 5 months ago

Looking for a champion! I consider this feature can be very useful TBH.

asyncapi / spec

[FEATURE REQUEST] Channel deprecation/sunset #305

When Which How Version

Design Time vs Runtime

alternativeChannel: this is a detail that should be in release notes, or in a reason if someone is too lazy. I can't imagine what I can use this field for programmatically. I would not automatically switch to a new channel, deprecations are things that need closer manual attention.