[APIC] Add API import scenario

dlepow · dlepow · commit dfda9ea19b46 · 2024-03-08T11:29:22.000-08:00
diff --git a/articles/api-center/import-api-management-apis.md b/articles/api-center/import-api-management-apis.md
@@ -4,7 +4,7 @@ description: Add APIs to your Azure API center inventory from your API Managemen
 author: dlepow
 ms.service: api-center
 ms.topic: how-to
-ms.date: 03/07/2024
+ms.date: 03/08/2024
 ms.author: danlep 
 ms.custom: devx-track-azurecli
 # Customer intent: As an API program manager, I want to add APIs that are managed in my Azure API Management instance to my API center.
@@ -16,18 +16,15 @@ This article shows how to import (add) APIs from an Azure API Management instanc
 
 This article shows two options for using the Azure CLI to add APIs to your API center from API Management:
 
-* Export an API from API Management to an API definition using the [az apim api export](/cli/azure/apim/api#az-apim-api-export) command. Then, run [az apic api register](/cli/azure/apic/api#az-apic-api-register) to register the API in your API center, using the API definition.
+* **Option 1** - Export an API definition from an API Management instance using the [az apim api export](/cli/azure/apim/api#az-apim-api-export) command. Then, import the definition to your API center. 
 
-* Bulk-import APIs from API Management to your API center using the [az apic service import-from-apim](/cli/azure/apic/service#az-apic-service-import-from-apim) command.
+    Possible ways to import an API definition exported from API Management include:
+    * Run [az apic api register](/cli/azure/apic/api#az-apic-api-register) to register a new API in your API center.
+    * Run [az apic api definition import-specification](/cli/azure/apic/api/definition#az-apic-api-definition-import-specification) to import the API definition to an existing API.
 
-When you add an API from an API Management instance to your API center using the bulk-import option, the following happens automatically:
-
-* The API's [versions](key-concepts.md#api-version), [definitions](key-concepts.md#api-definition), and [deployment](key-concepts.md#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](key-concepts.md#environment).
-
-After adding an API from API Management, you can add metadata and documentation in your API center to help stakeholders discover, understand, and consume the API.
+* **Option 2** - Bulk-import APIs from API Management to your API center using the [az apic service import-from-apim](/cli/azure/apic/service#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.
 
 > [!VIDEO https://www.youtube.com/embed/SuGkhuBUV5k]
 
@@ -37,7 +34,7 @@ After adding an API from API Management, you can add metadata and documentation
 
 * An API center in your Azure subscription. If you haven't created one, see [Quickstart: Create your API center](set-up-api-center.md).
 
-* One or more instances of Azure API Management, in the same or a different subscription in your directory. If you haven't created one, see [Create an Azure API Management instance](../api-management/get-started-create-service-instance.md).
+* One or more instances of Azure API Management, in the same or a different subscription. When you use the bulk-import option, 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](../api-management/get-started-create-service-instance.md).
 
 * One or more APIs managed in your API Management instance that you want to add to your API center. 
 
@@ -50,67 +47,89 @@ After adding an API from API Management, you can add metadata and documentation
     > [!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 from API Management and register it in your API center
-
-First, export an API from your API Management instance to an API definition using the [az apim api export](/cli/azure/apim/api#az-apim-api-export) command. For example:
+## 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](/cli/azure/apim/api#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 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*.
+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*. 
 
-```azurecli-interactive
+```azurecli
 #! /bin/bash
 az apim api export --api-id my-api --resource-group myResourceGroup \
     --service-name myAPIManagement --export-format OpenApiJsonFile \
     --file-path /path/to/folder
 ```
 
+```azurecli
+#! 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
 
-The following example exports the API with identifier *my-api* in the *myAPIManagement* instance of API. The API is exported in OpenApiJson format to a URL in Azure storage. The URL is available for approximately 5 minutes.
+The following example exports the API with identifier *my-api* in the *myAPIManagement* instance of API. The API is exported in OpenApiJson format to a URL in Azure storage. The URL is available for approximately 5 minutes. The value of the URL is stored in the *$link* variable.
 
-```azurecli-interactive
+```azurecli
+#! /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)
+    --service-name myAPIManagement --export-format OpenApiJsonUrl --query properties.value.link \
+    --output tsv)
 ```
 
-The URL appears in the command output. You can use the link to download the API definition file.
-
-```output
-[...]
-  "name": "my-api",
-  "properties": {
-    "format": "openapi+json-link",
-    "value": {
-      "link": "https://xxxxxxxxxxxxxxxxx.blob.core.windows.net/api-export/My API......."
-    [...]
-    }
-  }
-
+```azurecli
+# 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
 
-### Import local API definition to your API center
-
-Then, use the [az apic api register](/cli/azure/apic/api#az-apic-api-register) command to register the API in your API center, using the API definition.
+You can register a new API in your API center from the exported definition by using the [az apic api register](/cli/azure/apic/api#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*.
 
-```azurecli-interactive
-az apic api register --resource-group myResourceGroup \
-    --service myAPICenter --api-location "/Path/to/definitionFile.json
+```azurecli
+az apic api register --resource-group myResourceGroup --service myAPICenter --api-location "/path/to/definitionFile.json
 ```
 
-### Import API definition from a URL to your API center
+### Import API definition to an existing API in your API center
 
-The following example registers an API in the *myAPICenter* API center from an OpenAPI definition file at a URL whose value is stored in the *$link* variable.
+The following example uses the [az apic api definition import-specification](/cli/azure/apic/api/definition#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.
 
-```azurecli-interactive
+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](manage-apis-azure-cli.md#register-api-api-version-and-definition).
+
+```azurecli
+#! /bin/bash
+az apic api definition import-specification \
+    --resource-group myResourceGroup --service myAPICenter \
+    --api-name my-api --version-name v1-0-0 \
+    --definition-name openapi --format "link" --value '$link' \
+    --specification '{"name":"openapi","version":"3.0.2"}'
+```
 
+```azurecli
+# PowerShell syntax
+az apic api definition import-specification `
+    --resource-group myResourceGroup --service myAPICenter `
+    --api-name my-api --version-name v1-0-0 `
+    --definition-name openapi --format "link" --value '$link' `
+    --specification '{"name":"openapi","version":"3.0.2"}'
 ```
 
 ## Option 2: Bulk-import APIs from your API Management instance
 
+The following are steps to bulk-import APIs from your API Management instance to your API center using the [az apic service import-from-apim](/cli/azure/apic/service#az-apic-service-import-from-apim) command.
+
+When you add APIs from an API Management instance to your API center using the bulk-import option, the following happens automatically:
+    
+* Each API's [versions](key-concepts.md#api-version), [definitions](key-concepts.md#api-definition), and [deployment](key-concepts.md#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](key-concepts.md#environment).
+
 ### Add a managed identity in your API center
 
 For this scenario, your API center uses a [managed identity](/entra/identity/managed-identities-azure-resources/overview) to access APIs in your API Management instance. You can use either a system-assigned or user-assigned managed identity. If you haven't added a managed identity in your API center, you can add it in the Azure portal or by using the Azure CLI. 
@@ -128,7 +147,7 @@ For this scenario, your API center uses a [managed identity](/entra/identity/man
 
 Set the system-assigned identity in your API center using the following [az apic service update](/cli/azure/apic/service#az-apic-service-update) command. Substitute the names of your API center and resource group:
 
-```azurecli-interactive 
+```azurecli 
 az apic service update --name <api-center-name> --resource-group <resource-group-name> --identity '{"type": "SystemAssigned"}'
 ```
 ---
@@ -149,7 +168,7 @@ To add a user-assigned identity, you need to create a user-assigned identity res
 
 1. Create a user-assigned identity.
 
-    ```azurecli-interactive
+    ```azurecli
     az identity create --resource-group <resource-group-name> --name <identity-name> 
     ```
 
@@ -176,7 +195,7 @@ To add a user-assigned identity, you need to create a user-assigned identity res
 
 1. Add the user-assigned identity to your API center using the following [az apic service update](/cli/azure/apic/service#az-apic-service-update) command. Substitute the names of your API center and resource group, and pass the JSON file as the value of the `--identity` parameter. Here, the JSON file is named `identity.json`.
 
-    ```azurecli-interactive 
+    ```azurecli 
     az apic service update --name <api-center-name> --resource-group <resource-group-name> --identity "@identity.json"
     ```
 ---
@@ -201,45 +220,45 @@ To allow import of APIs, assign your API center's managed identity the **API Man
 1. Get the principal ID of the identity. If you're configuring a system-assigned identity, use the [az apic service show](/cli/azure/apic/service#az-apic-service-show) command. For a user-assigned identity, use [az identity show](/cli/azure/identity#az-identity-show).
 
     **System-assigned identity**
-    ```azurecli-interactive
+    ```azurecli
     #! /bin/bash
     apicObjID=$(az apic service show --name <api-center-name> \
         --resource-group <resource-group-name> \
         --query "identity.principalId" --output tsv)
     ```
 
-    ```azurecli-interactive
+    ```azurecli
     # PowerShell syntax
     $apicObjID=$(az apic service show --name <api-center-name> `
         --resource-group <resource-group-name> `
         --query "identity.principalId" --output tsv)
     ```
 
     **User-assigned identity**
-    ```azurecli-interactive
+    ```azurecli
     #! /bin/bash   
     apicObjID=$(az identity show --name <identity-name> --resource-group <resource-group-name> --query "principalId" --output tsv)
     ```
     
-    ```azurecli-interactive
+    ```azurecli
     # PowerShell syntax   
     $apicObjID=$(az identity show --name <identity-name> --resource-group <resource-group-name> --query "principalId" --output tsv)
     ```
 1. Get the resource ID of your API Management instance using the [az apim show](/cli/azure/apim#az-apim-show) command.
  
-    ```azurecli-interactive
+    ```azurecli
     #! /bin/bash
     apimID=$(az apim show --name <apim-name> --resource-group <resource-group-name> --query "id" --output tsv)
     ```
 
-    ```azurecli-interactive
+    ```azurecli
     # PowerShell syntax
     $apimID=$(az apim show --name <apim-name> --resource-group <resource-group-name> --query "id" --output tsv)
     ```
 
 1. Assign the managed identity the **API Management Service Reader** role in your API Management instance using the [az role assignment create](/cli/azure/role/assignment#az-role-assignment-create) command.
 
-    ```azurecli-interactive
+    ```azurecli
     #! /bin/bash
     scope="${apimID:1}"
 
@@ -250,7 +269,7 @@ To allow import of APIs, assign your API center's managed identity the **API Man
         --scope $scope 
     ```
     
-    ```azurecli-interactive
+    ```azurecli
     #! PowerShell syntax
     $scope=$apimID.substring(1)
 
@@ -276,19 +295,19 @@ 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](/cli/azure/apim#az-apim-show) command.
 
-    ```azurecli-interactive
+    ```azurecli
     #! /bin/bash
     apimID=$(az apim show --name <apim-name> --resource-group <resource-group-name> --query id --output tsv)
     ```
 
-    ```azurecli-interactive
+    ```azurecli
     # PowerShell syntax
     $apimID=$(az apim show --name <apim-name> --resource-group <resource-group-name> --query id --output tsv)
     ```
     
 1. 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.
 
-    ```azurecli-interactive
+    ```azurecli
     az apic service import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> --source-resource-ids $apimID/apis/*  
     ```
 
@@ -301,19 +320,19 @@ 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](/cli/azure/apim#az-apim-show) command.
 
-    ```azurecli-interactive
+    ```azurecli
     #! /bin/bash
     apimID=$(az apim show --name <apim-name> --resource-group <resource-group-name> --query id --output tsv)
     ```
 
-    ```azurecli-interactive
+    ```azurecli
     # PowerShell syntax
     $apimID=$(az apim show --name <apim-name> --resource-group <resource-group-name> --query id --output tsv)
     ```
     
 1. 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.
 
-    ```azurecli-interactive
+    ```azurecli
     az apic service import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> --source-resource-ids $apimID/apis/<api-name>    
     ```
     
