Get the answers to common questions, patterns, and best practices for Azure API Management.
Frequently asked questions
- What does it mean when a feature is in preview?
- How can I secure the connection between the API Management gateway and my back-end services?
- How do I copy my API Management service instance to a new instance?
- Can I manage my API Management instance programmatically?
- How do I add a user to the Administrators group?
- Why is the policy that I want to add unavailable in the policy editor?
- How do I use API versioning in API Management?
- How do I set up multiple environments in a single API?
- Can I use SOAP with API Management?
- Is the API Management gateway IP address constant? Can I use it in firewall rules?
- Can I configure an OAuth 2.0 authorization server with AD FS security?
- What routing method does API Management use in deployments to multiple geographic locations?
- Can I use an Azure Resource Manager template to create an API Management service instance?
- Can I use a self-signed SSL certificate for a back end?
- Why do I get an authentication failure when I try to clone a GIT repository?
- Does API Management work with Azure ExpressRoute?
- Why do we require a dedicated subnet in Resource Manager style VNETs when API Management is deployed into them?
- What is the minimum subnet size needed when deploying API Management into a VNET?
- Can I move an API Management service from one subscription to another?
- Are there restrictions on or known issues with importing my API?
How can I ask the Microsoft Azure API Management team a question?
You can contact us by using one of these options:
- Post your questions in our API Management MSDN forum.
- Send an email to email@example.com.
- Send us a feature request in the Azure feedback forum.
What does it mean when a feature is in preview?
When a feature is in preview, it means that we're actively seeking feedback on how the feature is working for you. A feature in preview is functionally complete, but it's possible that we'll make a breaking change in response to customer feedback. We recommend that you don't depend on a feature that is in preview in your production environment. If you have any feedback on preview features, please let us know through one of the contact options in How can I ask the Microsoft Azure API Management team a question?.
How can I secure the connection between the API Management gateway and my back-end services?
You have several options to secure the connection between the API Management gateway and your back-end services. You can:
- Use HTTP basic authentication. For more information, see Configure API settings.
- Use SSL mutual authentication as described in How to secure back-end services by using client certificate authentication in Azure API Management.
- Use IP whitelisting on your back-end service. If you have a Standard or Premium tier API Management instance, the IP address of the gateway remains constant. You can set your whitelist to allow this IP address. You can get the IP address of your API Management instance on the Dashboard in the Azure portal.
- Connect your API Management instance to an Azure Virtual Network.
How do I copy my API Management service instance to a new instance?
You have several options if you want to copy an API Management instance to a new instance. You can:
- Use the backup and restore function in API Management. For more information, see How to implement disaster recovery by using service backup and restore in Azure API Management.
- Create your own backup and restore feature by using the API Management REST API. Use the REST API to save and restore the entities from the service instance that you want.
- Download the service configuration by using Git, and then upload it to a new instance. For more information, see How to save and configure your API Management service configuration by using Git.
Can I manage my API Management instance programmatically?
Yes, you can manage API Management programmatically by using:
- The API Management REST API.
- The Microsoft Azure ApiManagement Service Management Library SDK.
- The Service deployment and Service management PowerShell cmdlets.
How do I add a user to the Administrators group?
Here's how you can add a user to the Administrators group:
- Sign in to the Azure portal.
- Go to the resource group that has the API Management instance you want to update.
- In API Management, assign the Api Management Contributor role to the user.
Now the newly added contributor can use Azure PowerShell cmdlets. Here's how to sign in as an administrator:
- Use the
Login-AzureRmAccountcmdlet to sign in.
- Set the context to the subscription that has the service by using
Set-AzureRmContext -SubscriptionID <subscriptionGUID>.
- Get a single sign-on URL by using
Get-AzureRmApiManagementSsoToken -ResourceGroupName <rgName> -Name <serviceName>.
- Use the URL to access the admin portal.
Why is the policy that I want to add unavailable in the policy editor?
If the policy that you want to add appears dimmed or shaded in the policy editor, be sure that you are in the correct scope for the policy. Each policy statement is designed for you to use in specific scopes and policy sections. To review the policy sections and scopes for a policy, see the policy's Usage section in API Management policies.
How do I use API versioning in API Management?
You have a few options to use API versioning in API Management:
- In API Management, you can configure APIs to represent different versions. For example, you might have two different APIs, MyAPIv1 and MyAPIv2. A developer can choose the version that the developer wants to use.
- You also can configure your API with a service URL that doesn't include a version segment, for example, https://my.api. Then, configure a version segment on each operation's Rewrite URL template. For example, you can have an operation with a URL template called /resource and a Rewrite URL template called /v1/Resource. You can change the version segment value separately for each operation.
- If you'd like to keep a "default" version segment in the API's service URL, on selected operations, set a policy that uses the Set backend service policy to change the back-end request path.
How do I set up multiple environments in a single API?
To set up multiple environments, for example, a test environment and a production environment, in a single API, you have two options. You can:
- Host different APIs on the same tenant.
- Host the same APIs on different tenants.
Can I use SOAP with API Management?
SOAP pass-through support is now available. Administrators can import the WSDL of their SOAP service, and Azure API Management will create a SOAP front end. Developer portal documentation, test console, policies and analytics are all available for SOAP services.
Is the API Management gateway IP address constant? Can I use it in firewall rules?
At the Standard and Premium tiers, the public IP address (VIP) of the API Management tenant is static for the lifetime of the tenant, with some exceptions. The IP address changes in these circumstances:
- The service is deleted and then re-created.
- The service subscription is suspended or warned (for example, for nonpayment) and then reinstated.
- You add or remove Azure Virtual Network (you can use Virtual Network only at the Developer and Premium tier).
For multi-region deployments, the regional address changes if the region is vacated and then reinstated (you can use multi-region deployment only at the Premium tier).
Premium tier tenants that are configured for multi-region deployment are assigned one public IP address per region.
You can get your IP address (or addresses, in a multi-region deployment) on the tenant page in the Azure portal.
Can I configure an OAuth 2.0 authorization server with AD FS security?
To learn how to configure an OAuth 2.0 authorization server with Active Directory Federation Services (AD FS) security, see Using ADFS in API Management.
What routing method does API Management use in deployments to multiple geographic locations?
API Management uses the performance traffic routing method in deployments to multiple geographic locations. Incoming traffic is routed to the closest API gateway. If one region goes offline, incoming traffic is automatically routed to the next closest gateway. Learn more about routing methods in Traffic Manager routing methods.
Can I use an Azure Resource Manager template to create an API Management service instance?
Yes. See the Azure API Management Service QuickStart templates.
Can I use a self-signed SSL certificate for a back end?
Yes. Here's how to use a self-signed Secure Sockets Layer (SSL) certificate for a back end:
- Create a Backend entity by using API Management.
- Set the skipCertificateChainValidation property to true.
- If you no longer want to allow self-signed certificates, delete the Backend entity, or set the skipCertificateChainValidation property to false.
Why do I get an authentication failure when I try to clone a Git repository?
If you use Git Credential Manager, or if you're trying to clone a Git repository by using Visual Studio, you might run into a known issue with the Windows credentials dialog box. The dialog box limits password length to 127 characters, and it truncates the Microsoft-generated password. We are working on shortening the password. For now, please use Git Bash to clone your Git repository.
Does API Management work with Azure ExpressRoute?
Yes. API Management works with Azure ExpressRoute.
Why do we require a dedicated subnet in Resource Manager style VNETs when API Management is deployed into them?
The dedicated subnet requirement for API Management comes from the fact, that it is built on Classic (PAAS V1 layer) deployment model. While we can deploy into a Resource Manager VNET (V2 layer), there are consequences to that. The Classic deployment model in Azure is not tightly coupled with the Resource Manager model and so if you create a resource in V2 layer, the V1 layer doesn't know about it and problems can happen, such as API Management trying to use an IP that is already allocated to a NIC (built on V2). To learn more about difference of Classic and Resource Manager models in Azure refer to difference in deployment models.
What is the minimum subnet size needed when deploying API Management into a VNET?
The minimum subnet size needed to deploy API Management is /29, which is the minimum subnet size that Azure supports.
Can I move an API Management service from one subscription to another?
Yes. To learn how, see Move resources to a new resource group or subscription.
Are there restrictions on or known issues with importing my API?
Known issues and restrictions for Open API(Swagger), WSDL and WADL formats.