Azure API Management Integration

Microsoft Azure API Management allows developers to publish and maintain APIs in the Azure cloud. API Hub for Design integrates with Azure API Management, which allows you to easily export your API definitions to Azure. This way you can design your APIs on API Hub for Design, then deploy your API design to your Azure API Management instance from API Hub for Design, keeping the APIs updated with any changes you make to the design.

The vendor extension x-azure-api-id will be automatically added to your API definition to link it with the API saved to your Azure API Management service instance.

Important

API Hub for Design users who configured this integration for OpenAPI 2.0 definitions before July 9, 2019 need to re-authenticate the integration by clicking Sign in with Microsoft in the integration settings. The new authentication method uses dynamically issued access tokens, unlike the old tokens that had to be generated manually and were valid for 30 days only.

Requirements

To use the integration, you need an active Microsoft Azure subscription. You can sign up at https://azure.microsoft.com. An Azure subscription is also included in the Visual Studio subscription and some other Microsoft subscriptions.

Note

This integration works only with the global Azure cloud (portal.azure.com), it does not support Azure Government Cloud (portal.azure.us).

Supported OpenAPI versions

This integration supports OpenAPI 2.0 and OpenAPI 3.0. API Hub for Design On-Premise users need v. 1.20.0 or later to use OpenAPI 3.0 definitions with Azure API Management.

Note

Azure API Management does not support some features of the OpenAPI Specification, specifically, recursive schemas. API definitions that use unsupported features cannot be imported to Azure.

Considerations

  • The integration is one-way, which means your API definitions go only from API Hub for Design to Azure API Management. You should edit your API definitions in API Hub for Design only.

  • The integration is bound to a specific version of the API and is not copied when you add a new version. To integrate different API versions with Azure, you need to add the integration to each version separately.Versioning

1. Create an Azure API management service instance

To use the integration, you must have an API Management service instance running in the Azure cloud. If you do not have one yet, follow the instructions in Create an API Management service instance.

API Management service instance in Azure

Click the image to enlarge it.

2. Configure the integration

  1. Open your API in the API Hub for Design editor.

  2. If the API has several versions, select the version you want to push to Azure API Management.

    API_screenshot_API_versions_01.png

  3. If this version is published, unpublish it. Only unpublished APIs can be integrated with Azure API Management.

  4. Click the API name, switch to the Integrations tab, and click Add New Integrations:

    Add New Integration menu command

  5. Select Azure API Management from the list of integrations.

  6. Enter the integration parameters:

    • Name – Required. The display name for the integration.

    • Azure API Management service instance name – Required. The name of your Azure API Management service instance as it appears in the resources list in the Azure portal.

      Azure API Management service instance name

      The service instance name can also be found in the developer portal URL. It is the {name} part of the URL - https://{name}.portal.azure-api.net

    • Azure API Identifier – Leave it blank to create a new API in Azure API Management. Alternatively, if you want to update an existing API in Azure API Management, specify the API name here or in the x-azure-api-id key at the root level of your API definition.

      Tip: The API name can be found in the API settings in Azure:

      API name in Azure

      Click the image to enlarge it.

    • API URL Suffix – This suffix will be appended to the hostname of your API Management service instance to create a public URL for your API. As such, it must be unique within an API Management service instance.

      Examples:

      API URL Suffix

      Public base URL of the API in Azure

      myapi

      https://{instance}.azure-api.net/myapi

      myapi/reports

      https://{instance}.azure-api.net/myapi/reports

      If omitted, the suffix will be set to an empty string for OpenAPI 3.0 definitions, or the basePath value for OpenAPI 2.0 definitions.

    • Management API Access Token – Click Sign in with Microsoft. You will be prompted to log into your Azure account and authorize the connection with API Hub for Design.

    • Enable – Keep this check box selected for the integration to work. Unselect it to disable the integration temporarily.

  7. Click Create and Execute.

That’s it! Now, every time you save this version of the API, the definition is synced and updated in Azure API Management.

You can see the created or updated API in your Azure API Management portal:

API in Azure API Management

Click the image to enlarge it.

Troubleshooting

If there was a problem with pushing your API to Azure, you will see an Integration Error at the top of the API Hub for Design Editor. Below are some common errors you might run into and their solutions:

A definition must have a unique basePath section

All APIs in Azure API Management must have a unique basePath. This error means that an API with the same basePath already exists. To resolve the problem, specify another basePath in your API definition on API Hub for Design.

401 Unauthorized errors

This usually means that the access token has expired. To resolve the issue, open the integration settings and click Sign in with Microsoft. If there is no "Sign in" button, generate an access token manually as explained above and specify the new token in the integration settings.

See Also

In this section:
© 2024
Publication date: