How best keep Azure OpenAI up-to-date on API Management instace?

Question

Hi Azure Support Team,

There is a new option to import the Azure OpenAI API into the API Management. https://learn.microsoft.com/en-us/azure/api-management/azure-openai-api-from-specification

Let's say I import the OpenAI API based on the existing Azure OpenAI resource and configure it, including subscriptions for various consumers.

How should I update the API when Azure OpenAI changes its underlying API specification? Should I keep track of the API changes myself to act in time, or can Azure notify me when a new method is added or a data structure changes? Can it be automated without affecting the existing configuration?

Answer 1

When you import the Azure OpenAI API into Azure API Management (APIM) using the method described in Microsoft's documentation, you create a snapshot of the API specification at the time of import. That snapshot is not automatically updated when the Azure OpenAI team changes the API. Effectively, you must track API changes manually. Azure OpenAI does not push notifications to APIM about API changes such as:

• New endpoints or operations
• Modified request/response schemas
• Deprecated or removed methods

This means that you'd need to:

• Regularly check the Azure OpenAI OpenAPI specification (or official changelogs/releases)
• Compare your existing imported spec with the latest version

To update the API in APIM:

• Re-import the updated OpenAPI specification into the same API version within APIM.
  • This updates the API schema.
  • You can do this via the Azure Portal, ARM templates, Bicep, Terraform, or APIM DevOps Toolkit.
• APIM preserves policies and configurations (e.g., products, rate limits, subscription keys) as long as the API name and operation IDs remain consistent.
• Changes that alter operation IDs or remove endpoints may require manual adjustments to policies or consumer applications.

You can semi-automate the update process using:

• A CI/CD pipeline (e.g., GitHub Actions, Azure DevOps)
• The latest OpenAPI spec fetched from GitHub or your own mirror
• Tools like az apim api import or ARM deployments

However, automation requires safeguards:

• Validate changes in a non-production APIM instance
• Use API versioning if breaking changes are detected
• Keep consumers isolated from updates until verified

There is no native Azure notification system for when the Azure OpenAI API spec changes. Instead, you could:

• Watch the GitHub repo for Azure OpenAI REST API specs
• Use tools like GitHub RSS feeds or webhooks
• Subscribe to the Azure OpenAI changelog

---

If the above response helps answer your question, remember to "Accept Answer" so that others in the community facing similar issues can easily find the solution. Your contribution is highly appreciated.

hth

Marcin