Import APIs to your API center from Azure API Management

Article
07/03/2024

This article shows how to import (add) APIs from an Azure API Management instance to your API center using the Azure CLI. Adding APIs from API Management to your API inventory helps make them discoverable and accessible to developers, API program managers, and other stakeholders in your organization.

This article shows two options for using the Azure CLI to add APIs to your API center from API Management:

Option 1 - Export an API definition from an API Management instance using the az apim api export command. Then, import the definition to your API center.

Possible ways to import an API definition exported from API Management include:
- Run az apic api register to register a new API in your API center.
- Run az apic api definition import-specification to import the API definition to an existing API.
Option 2 - Import APIs directly from API Management to your API center using the az apic import-from-apim command.

After importing API definitions or APIs from API Management, you can add metadata and documentation in your API center to help stakeholders discover, understand, and consume the API.

Tip

You can also set up automatic synchronization of APIS from API Management to your API center. For more information, see Link an API Management instance to synchronize APIs to your API center.

Prerequisites

An API center in your Azure subscription. If you haven't created one, see Quickstart: Create your API center.
One or more instances of Azure API Management, in the same or a different subscription. When you import APIs directly from API Management, the API Management instance and API center must be in the same directory. If you haven't created one, see Create an Azure API Management instance.
One or more APIs managed in your API Management instance that you want to add to your API center.
For Azure CLI:
- Use the Bash environment in Azure Cloud Shell. For more information, see Quickstart for Bash in Azure Cloud Shell.
- If you prefer to run CLI reference commands locally, install the Azure CLI. If you're running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, see How to run the Azure CLI in a Docker container.
  - If you're using a local installation, sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For other sign-in options, see Sign in with the Azure CLI.
  - When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see Use extensions with the Azure CLI.
  - Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.
Note

az apic commands require the apic-extension Azure CLI extension. If you haven't used az apic commands, the extension can be installed dynamically when you run your first az apic command, or you can install the extension manually. Learn more about Azure CLI extensions.

See the release notes for the latest changes and updates in the apic-extension.

Note

Azure CLI command examples in this article can run in PowerShell or a bash shell. Where needed because of different variable syntax, separate command examples are provided for the two shells.

Option 1: Export an API definition from API Management and import it to your API center

First, export an API from your API Management instance to an API definition using the az apim api export command. Depending on your scenario, you can export the API definition to a local file or a URL.

Export API to a local API definition file

The following example command exports the API with identifier my-api in the myAPIManagement instance of API. The API is exported in OpenApiJson format to a local OpenAPI definition file at the path you specify.

#! /bin/bash
az apim api export --api-id my-api --resource-group myResourceGroup \
    --service-name myAPIManagement --export-format OpenApiJsonFile \
    --file-path "/path/to/folder"

# Formatted for PowerShell
az apim api export --api-id my-api --resource-group myResourceGroup `
    --service-name myAPIManagement --export-format OpenApiJsonFile `
    --file-path '/path/to/folder'

Export API to a URL

In the following example, az apim api export exports the API with identifier my-api in OpenApiJson format to a URL in Azure storage. The URL is available for approximately 5 minutes. Here, the value of the URL is stored in the $link variable.

#! /bin/bash
link=$(az apim api export --api-id my-api --resource-group myResourceGroup \
    --service-name myAPIManagement --export-format OpenApiJsonUrl --query properties.value.link \
    --output tsv)

# Formatted for PowerShell
$link=$(az apim api export --api-id my-api --resource-group myResourceGroup `
    --service-name myAPIManagement --export-format OpenApiJsonUrl --query properties.value.link `
    --output tsv)

Register API in your API center from exported API definition

You can register a new API in your API center from the exported definition by using the az apic api register command.

The following example registers an API in the myAPICenter API center from a local OpenAPI definition file named definitionFile.json.

az apic api register --resource-group myResourceGroup --service-name myAPICenter --api-location "/path/to/definitionFile.json"

Import API definition to an existing API in your API center

The following example uses the az apic api definition import-specification command to import an API definition to an existing API in the myAPICenter API center. Here, the API definition is imported from a URL stored in the $link variable.

This example assumes you have an API named my-api and an associated API version v1-0-0 and definition entity openapi in your API center. If you don't, see Add APIs to your API center.

#! /bin/bash
az apic api definition import-specification \
    --resource-group myResourceGroup --service-name myAPICenter \
    --api-id my-api --version-id v1-0-0 \
    --definition-id openapi --format "link" --value '$link' \
    --specification '{"name":"openapi","version":"3.0.2"}'

# Formatted for PowerShell
az apic api definition import-specification `
    --resource-group myResourceGroup --service-name myAPICenter `
    --api-id my-api --version-id v1-0-0 `
    --definition-id openapi --format "link" --value '$link' `
    --specification '{"name":"openapi","version":"3.0.2"}'

Option 2: Import APIs directly from your API Management instance

The following are steps to import APIs from your API Management instance to your API center using the az apic import-from-apim command. This command is useful when you want to import multiple APIs from API Management to your API center, but you can also use it to import a single API.

When you add APIs from an API Management instance to your API center using az apic import-from-apim, the following happens automatically:

Each API's versions, definitions, and deployment information are copied to your API center.
The API receives a system-generated API name in your API center. It retains its display name (title) from API Management.
The Lifecycle stage of the API is set to Design.
Azure API Management is added as an environment.

Add a managed identity in your API center

For this scenario, your API center uses a managed identity to access APIs in your API Management instance. Depending on your needs, configure either a system-assigned or one or more user-assigned managed identities.

The following examples show how to configure a system-assigned managed identity by using the Azure portal or the Azure CLI. At a high level, configuration steps are similar for a user-assigned managed identity.

Portal
Azure CLI

In the portal, navigate to your API center.
In the left menu, under Security, select Managed identities.
Select System assigned, and set the status to On.
Select Save.

Set the system-assigned identity in your API center using the following az apic update command. Substitute the names of your API center and resource group:

az apic update --name <api-center-name> --resource-group <resource-group-name> --identity '{"type": "SystemAssigned"}'

Assign the managed identity the API Management Service Reader role

To allow import of APIs, assign your API center's managed identity the API Management Service Reader role in your API Management instance. You can use the portal or the Azure CLI.

Portal
Azure CLI

In the portal, navigate to your API Management instance.
In the left menu, select Access control (IAM).
Select + Add role assignment.
On the Add role assignment page, set the values as follows:
1. On the Role tab - Select API Management Service Reader.
2. On the Members tab, in Assign access to - Select Managed identity > + Select members.
3. On the Select managed identities page - Select the system-assigned managed identity of your API center that you added in the previous section. Click Select.
4. Select Review + assign.

Get the principal ID of the identity. For a system-assigned identity, use the az apic show command.

#! /bin/bash
apicObjID=$(az apic show --name <api-center-name> \
    --resource-group <resource-group-name> \
    --query "identity.principalId" --output tsv)

# Formatted for PowerShell
$apicObjID=$(az apic show --name <api-center-name> `
    --resource-group <resource-group-name> `
    --query "identity.principalId" --output tsv)

Get the resource ID of your API Management instance using the az apim show command.

#! /bin/bash
apimID=$(az apim show --name <apim-name> --resource-group <resource-group-name> --query "id" --output tsv)

# Formatted for PowerShell
$apimID=$(az apim show --name <apim-name> --resource-group <resource-group-name> --query "id" --output tsv)

Assign the managed identity the API Management Service Reader role in your API Management instance using the az role assignment create command.

#! /bin/bash
scope="${apimID:1}"

az role assignment create \
    --role "API Management Service Reader Role" \
    --assignee-object-id $apicObjID \
    --assignee-principal-type ServicePrincipal \
    --scope $scope

# Formatted for PowerShell
$scope=$apimID.substring(1)

az role assignment create `
    --role "API Management Service Reader Role" `
    --assignee-object-id $apicObjID `
    --assignee-principal-type ServicePrincipal `
    --scope $scope

Import APIs from API Management

Use the az apic import-from-apim command to import one or more APIs from your API Management instance to your API center.

Note

This command depends on a managed identity configured in your API center that has read permissions to the API Management instance. If you haven't added or configured a managed identity, see Add a managed identity in your API center earlier in this article.
If your API center has multiple managed identities, the command searches first for a system-assigned identity. If none is found, it picks the first user-assigned identity in the list.

Import all APIs from an API Management instance

In the following command, substitute the names of your API center, your API center's resource group, your API Management instance, and your instance's resource group. Use * to specify all APIs from the API Management instance.

#! /bin/bash
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> \
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> \
    --apim-apis '*'

# Formatted for PowerShell
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> `
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> `
    --apim-apis '*'

Note

If your API Management instance has a large number of APIs, import to your API center might take some time.

Import a specific API from an API Management instance

Specify an API to import using its name from the API Management instance.

In the following command, substitute the names of your API center, your API center's resource group, your API Management instance, and your instance's resource group. Pass an API name such as petstore-api using the --apim-apis parameter.

#! /bin/bash
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> \
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> \
    --apim-apis 'petstore-api'

# Formatted for PowerShell
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> `
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> `
    --apim-apis 'petstore-api'

Note

Specify an API name using the API resource name in the API Management instance, not the display name. Example: petstore-api instead of Petstore API.

After importing APIs from API Management, you can view and manage the imported APIs in your API center.

Share via

Import APIs to your API center from Azure API Management

Prerequisites

Option 1: Export an API definition from API Management and import it to your API center

Export API to a local API definition file

Export API to a URL

Register API in your API center from exported API definition

Import API definition to an existing API in your API center

Option 2: Import APIs directly from your API Management instance

Add a managed identity in your API center

Assign the managed identity the API Management Service Reader role

Import APIs from API Management

Import all APIs from an API Management instance

Import a specific API from an API Management instance

Feedback

Additional resources

Share via

Import APIs to your API center from Azure API Management

Prerequisites

Option 1: Export an API definition from API Management and import it to your API center

Export API to a local API definition file

Export API to a URL

Register API in your API center from exported API definition

Import API definition to an existing API in your API center

Option 2: Import APIs directly from your API Management instance

Add a managed identity in your API center

Assign the managed identity the API Management Service Reader role

Import APIs from API Management

Import all APIs from an API Management instance

Import a specific API from an API Management instance

Related content

Feedback

Additional resources