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.