API deprecation support

[AnRei123]

Bug description

Over time, the list of deprecated APIs and operations gets longer and longer. The developer experience for newly onboarded partners gets worse and worse. And it looks very confusing to see all the legacy APIs and operations together with the current ones in long lists.

New API consumer must only see the list of APIs that are not deprecated yet. Nevertheless, for previous API consumers, the APIs and operations need to be still accessible. With the current DevPortal approach, all APIs and operations are listed irrespective of their deprecation status. The display cannot be controlled based on the deprecation status. Currently, is not possible to hide deprecated APIs and operations by default. Over time it gets harder and less comfortable for the API consumer to find the suitable and latest API for their required use case.

In the Swagger File definition, a deprecation field with a Boolean value for deprecated operations, parameters and schemas is defined/supported (https://swagger.io/specification/). But the value of this field seems currently not being reflected/supported by the APIM and DevPortal accordingly.

Expected behavior

We need as soon as possible a solution similar to what we describe in the following.

Principle: The expected behavior is that the API provider can use the deprecation field in the Swagger file to declare an operation as deprecated. If all operations of an API version are declared to be deprecated, the API version should be also labeled/tagged as deprecated in the ApimPortal and DevPortal.

APIM settings: This should be automatically reflected, in the API settings dialog by a greyed out field ("true").

Additionally, in the Frontend Settings of an operation, it should be possible to edit the value of the deprecation field.

DevPortal: 1) Hide deprecated APIs by default in the list of APIs and add a possibility to show deprecated APIs explicitly with a filter criteria or with an additional toggle button such as "Show deprecated APIs". Add a "deprecated" label/flag behind a list item to easily distinguish between current and deprecated operations right from the list in case the Show deprecated APIs toggle has been explicitly activated.

2) Hide deprecated operations by default in the list of operations and add a possibility to show deprecated operations explicitly with a filter criteria or with an additional toggle button such as "Show deprecated Operations". Add a "deprecated" label/flag behind a list item to easily distinguish between current and deprecated operations right from the list.

3) For the solution in the Developer Portal, it is very important that there is a way to create special deep links to the API details page that also shows the list of deprecated APIs - even when the deprecated items are configured to be hidden by default. This is important for the links that we provide in our e-mail notifications on deprecated APIs. Normal deep links to an API version should still hide deprecated operations by default - if the list of operation widget is configured accordingly. It must also be possible for deep links to dedicated operations that deprecated list items in the list of operations are shown.

4) The web widget "Product: APIs" that lists the associated API versions of a product should be configurable that way that deprecated APIs are hidden by default. Add here also a possibility to explicitly show deprecated APIs with a filter criteria or with an additional toggle button such as "Show deprecated APIs". Add a "deprecated" label/flag behind a list item to easily distinguish between current and deprecated API versions right from the list.

Thus, we expect to increase the usability and developer experience for our newly onboarded partners and to reduce the risk that already deprecated APIs are confusing our partners and get still be implemented in their codes.

Is your portal managed or self-hosted?

Managed

Environment

• Operating system: Windows 10
• Browser: Chrome
• Version: latest

[mikebudzynski]

Deprecation support is on our roadmap.

[sid6mathur]

@AnRei123 You are my new hero. I also feel the urge to label every single UX touchpoint with a yellow (or red!) marker like you have - but never gather enough patience to do it :) They are too many broken things in the show API and try API experience still unfortunately.

[tdysko-star]

Any update on that ? @mikebudzynski

[mikebudzynski]

No update at the moment - support for the "deprecated" property is on our roadmap, but we don't have an ETA. It first needs to be supported by the API Management service backend during the API creation or editing experience and then we will add support in the developer and Azure portals.

[mkowalskigps]

Any additional updates in terms of roadmap / ETA?

[Recio]

Hey,

This is a pretty significant oversight that was first detected in 2019 on issue #118, that's over 1000 issues ago. Any way we can contribute to this? Or get a clear indication on when this is planned to be supported?

[mikebudzynski]

We're actively working on the support for deprecation in API Management. You will be able to mark an API operation or a request parameter as deprecated (as specified by OpenAPI specification). In addition to that, you will also be able to mark a full API as deprecated. The deprecation status will be visible in the Azure portal and in the developer portal.

This feature requires us to implement changes in many components, including the management API, so it will take several months for it to be fully released.

[scoucheron]

Hello!

@mikebudzynski do you have an update on this? We have several users that has the need to mark their APIs as deprecated 👍

Would love an ETA or update on the roadmap 😄

[verschaevesiebe]

Hi All,

Still no ETA on this feature ? This has been supported by Swagger since a few years now and it's really annoying that we can't just use this in Azure API Management.

We're working with a big client that has 600 API's and we're deprecating a lot of them however in the portal nothing of this is visible. Can we not add this to the roadmap to already support the developer portal to showcase it without having the support of the API Management backend to add this ? I assume the portal is just reading the OpenAPI anyway so not much would change.

Please investigate

[Recio]

Hey,

Can get an ETA or more specific timeline on this, and if not is there any guidelines or documentation on how this can be managed differently?

Thanks

[stephenphoward]

This would seem to be a significant oversight for an enterprise API Management solution.

Is it possible to provide an ETA, including "don't know." This would be helpful for our planning purposes.

Thank you.

[mkowalskigps]

Bumping this issue / bug - any ETA / update on when this would be made available? Thanks!

[bernardpletikosa]

Any updates on this? From my perspective this just looks like an UI change that follows OpenAPI spec. I'm sure it's much more complicated in the background and needs more work, but an ETA must be possible if it's on the roadmap for so long.

[JohnAllenTech]

Can we get an update on this? It is a fairly reasonable expectation to be able to mark an endpoint as deprecated on the worlds second largest cloud provider

[cemusta]

Do you happen to have any news on this? or has this issue been deprecated?

[verschaevesiebe]

Bump, we're deploying our openAPI specifications directly to API Management and the deprecated: true is in there. Is developer portal relying on the OpenAPI spec directly or does it use an intermediary structure delivered from Azure backend itself ? Since if it only reads the OpenAPI, it should definently be an issue pull request.

Perhaps i can support on creating a pull-request for this ?