API / Product deprecation

[Sacratees]

How to mark exposed APIs or Product as deprecated in API management. Right now i could see the only option to update the descriptions.
Including deprecated flag in swagger does not work. Is there any better way available to mark exposed entities as deprecated?

How to efficiently deprecate an API and announce to consumers?

[mikebudzynski]

@Sacratees

Even though we currently don't support it, we have plans to allow API deprecation in API Management. You can let us know more details (or just upvote the item) here: https://feedback.azure.com/forums/248703-api-management/suggestions/6684898-mark-api-operations-as-obsolete-deprecated

Since your request has a much broader scope than the new developer portal, I will close this Issue.

[AnRei123]

We currently have the issue that an API version can be associated to two different API products. To call the API version, you need to subscribe at least to one of the API products. But when you decide to deprecate one of the two API products, this would mean a breaking change for the API consumer as he/she is required to change the subscription key in her/his deploy pipeline.
To avoid this, subscriptions would make more sense on API level and not on product level. Thus, subscription keys could be retained irrespective if you reorganize the associated parent APIs.
But currently, the approval workflow is not supported in the APIM portal on API level nor can the subscription be requested via a associated web widget in the managed DevPortal. When can we expect these improvements to be part of the APIM portal and managed DevPortal?

[mikebudzynski]

But when you decide to deprecate one of the two API products, this would mean a breaking change for the API consumer as he/she is required to change the subscription key in her/his deploy pipeline.

@AnRei123, deprecation is always a breaking change. API consumers need to be notified about the deprecation and provided with transition instructions. You might want to use separate phases for the deprecation and retirement. Deprecation is a warning to the consumers that the API / operation / product is no longer supported except for high severity security incidents. Retirement is when it stops working. Consumers have the time to transition to a new solution after the deprecation is announced but before the retirement happens.

[AnRei123]

Let me try to further depict the two scenarios that I mentioned above.

Scenario 1 (subscribe to API products only):

• API product A (discontinue: subscription key A) includes API xyz, v2
• API product B (continue: subscription key B) includes API xyz, v2
  As a developer who subscribed API product A, to continue consuming API xyz, v2, I need to manually subscribe to API product B and change the subscription key for the API call from subscription key A to subscription key B.

Scenario 2 (subscribe API products and subscribe to API versions):
In this scenario, API products, would only support to market dedicated bundles of API versions. The product subscription key would not be required anymore to consume the APIs. To consume the API, the subscription key for the API version would be required instead. Option: Subscription of the API version would be only possible if the the parent API product has been subscribed in advance (depending on the settings in the APIM portal).

• API product A (discontinue) includes API xyz, v2 (subscription key A)
• API product B (continue)) includes API xyz, v2 (subscription key A)
  As an API provider, I can market an API version via two different API products without introducing a breaking change to the API consumer if I decide to discontinue API product A. As an API consumer, I am able to consume an API version as long as the API version itself is discontinued, without any dependencies to any subscription key of a parent API product.

Do you plan to support a scenario such the herein depicted scenario 2 in future? If yes, when do you plan to make this feature available?