Why does Import-AzApiManagementApi overwrite my authorization server settings?

[keg7271]

https://docs.microsoft.com/en-us/powershell/module/az.apimanagement/import-azapimanagementapi?view=azps-8.0.0&source=docs

I am importing a OpenAPI document to an existing API for the purpose of updating the operations list. All other settings should remain unchanged. Also, where in an OpenAPI document are we supposed to indicate what APIM authorization server Id to use?

[dingmeng-xue]

@adrianhall , @KedarJoshi , please help to look into this question.

[keg7271]

The APIM extractor method described in the https://github.com/Azure/azure-api-management-devops-resource-kit is redundant. The swagger document already describes operations, schemas, etc. Why is Microsoft's recommendation to translate a web standard into a Microsoft proprietary ARM/Bicep format then import into APIM. Now the tooling behaves in such a way that forces us to use the extractor in some form because the import powershell command have undesirable side effects.

[adrianhall]

Hi Keg,

Microsoft doesn't "recommend" a specific import technique over others. We have several mechanisms for setting up the Azure API Management API based on an OpenAPI specification - some of these have side effects and others have limitations. It sounds like what you are requesting is not possible with the explicit set of features we have today. Please file your specific request to aka.ms/apimwish and we will take a look at what you need.

No further action required on the PowerShell module (since the product is working "as designed').

#please-close

[keg7271]

Hi @adrianhall

Actually the azure-api-management-devops-resource-kit clearly diagrams and documents that the "recommended" method is to create from OpenAPI documents to Resource Manager templates or extract from an existing instance of APIM into Resource Manager templates.

[adrianhall]

sorry to be argumentative here - it's not my intention. But yes, when using the DevOps Resource Kit (whose primary purpose is to integrate into an ARM pipeline), the recommended method is to use OAS documents to generate ARM templates. Not all customers use an ARM pipeline, or use an ARM pipeline only when creating the resources and not when managing APIs.

As a best practice, we recommend that you split the API deployment from the service deployment and manage your APIs separately. How you deal with your APIs is dependent on what type of APIs you have, how you describe them, and how you are deploying those APIs into production. SOAP APIs are managed differently from REST APIs, which are managed differently from GraphQL APIs. In addition, the way you deploy those APIs into production will differ from organization to organization - our philosophy is that you should be able to integrate the API deployment into whatever pipeline you already use; we shouldn't be forcing you to use a specific methodology.

As a result, we support Azure CLI and PowerShell, ARM templates, Bicep templates, creator/extractor (for DevOps toolkit) and REST APIs. Customers also use custom tooling (publisher is a tool that comes to mind that integrates with Git and only publishes the APIs that have changes during a PR process), Terraform, Pulumi, and others.

Is there a best practice? Best practices evolve over time, but we try to document our advice in the Azure Architecture Center. You can read the article on the current standard here: https://docs.microsoft.com/en-us/azure/architecture/example-scenario/integration/app-gateway-internal-api-management-function

Hope that help!

[keg7271]

Fair enough. Thanks for the perspective.

[keg7271]

However, my original question is still pending. Where in a OpenAPI document am I supposed to indicate which authorization server Id to use, as defined in APIM, for an API? OpenAPI documents are not specific to APIM authorization servers so why would this powershell command remove, or more specifically apply/associate an auth server defined in APIM? I can provide oAuth2 specifications but not an auth server Id.

[adrianhall]

You can't. It's a limitation of our OpenAPI specification import. Please put your expectation in at aka.ms/apimwish and we'll then have it tracked as a feature request.