Import APIs to your API center from Azure API Management

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 service 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.

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 is installed dynamically when you run your first az apic command. Learn more about Azure CLI extensions.

  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 named specificationFile.json.

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

#! PowerShell syntax
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)

# PowerShell syntax
$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 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 myAPICenter \
    --api-id my-api --version-id v1-0-0 \
    --definition-id openapi --format "link" --value '$link' \
    --specification '{"name":"openapi","version":"3.0.2"}'

# PowerShell syntax
az apic api definition import-specification `
    --resource-group myResourceGroup --service 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 service 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 service 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

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

Azure CLI

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

az apic service 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

1. In the portal, navigate to your API Management instance.
2. In the left menu, select Access control (IAM).
3. Select + Add role assignment.
4. 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.

Azure CLI

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

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

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

2. 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)
   

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

3. 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 
   

   #! PowerShell syntax
   $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 service 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

Use a wildcard (*) to specify all APIs from the API Management instance.

1. 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)
   

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

2. Use the az apic service import-from-apim command to import the APIs. Substitute the names of your API center and resource group, and use * to specify all APIs from the API Management instance.

   az apic service import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> --source-resource-ids $apimID/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.

1. 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)
   

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

2. Use the az apic service import-from-apim command to import the API. Substitute the names of your API center and resource group, and specify an API name from the API Management instance.

   az apic service import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> --source-resource-ids $apimID/apis/<api-name>    
   

   Note

   Specify <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.

Related content

• Azure CLI reference for Azure API Center
• Azure CLI reference for API Management
• Manage API inventory with Azure CLI commands
• Assign Azure roles to a managed identity
• Azure API Management documentation