Use the Azure CLI to manage your API inventory

This article shows how to use az apic api commands in the Azure CLI to add and configure APIs in your API center inventory. Use commands in the Azure CLI to script operations to manage your API inventory and other aspects of your API center.

Prerequisites

• An API center in your Azure subscription. If you haven't created one already, see Quickstart: Create 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.

Register API, API version, and definition

The following steps show how to create an API and associate a single API version and API definition. For background about the data model in Azure API Center, see Key concepts.

Create an API

Use the az apic api create command to create an API in your API center.

The following example creates an API named Petstore API in the myResourceGroup resource group and myAPICenter API center. The API is a REST API.

az apic api create  --resource-group myResourceGroup \
    --service myAPICenter --api-id petstore-api \
    --title "Petstore API" --type "rest"

Note

After creating an API, you can update the API's properties by using the az apic api update command.

Create an API version

Use the az apic api version create command to create a version for your API.

The following example creates an API version named v1-0-0 for the petstore-api API that you created in the previous section. The version is set to the testing lifecycle stage.

az apic api version create --resource-group myResourceGroup \
    --service myAPICenter --api-id petstore-api \
    --version-id v1-0-0 --title "v1-0-0" --lifecycle-stage "testing"

Create API definition and add specification file

Use the az apic api definition commands to add a definition and an accompanying specification file for an API version.

Create a definition

The following example uses the az apic api definition create command to create a definition named openapi for the petstore-api API version that you created in the previous section.

az apic api definition create --resource-group myResourceGroup \
    --service myAPICenter --api-id petstore-api \
    --version-id v1-0-0 --definition-id openapi --title "OpenAPI"

Import a specification file

Import a specification file to the definition using the az apic api definition import-specification command.

The following example imports an OpenAPI specification file from a publicly accessible URL to the openapi definition that you created in the previous step. The name and version properties of the specification resource are passed as JSON.

az apic api definition import-specification \
    --resource-group myResourceGroup --service myAPICenter \
    --api-id petstore-api --version-id v1-0-0 \
    --definition-id openapi --format "link" \
    --value 'https://petstore3.swagger.io/api/v3/openapi.json' \
    --specification '{"name":"openapi","version":"3.0.2"}'

Tip

You can import the specification file inline by setting the --format parameter to inline and passing the file contents using the --value parameter.

Export a specification file

To export an API specification from your API center to a local file, use the az apic api definition export-specification command.

The following example exports the specification file from the openapi definition that you created in the previous section to a local file named specificationFile.json.

az apic api definition export-specification \
    --resource-group myResourceGroup --service myAPICenter \
    --api-id petstore-api --version-id v1-0-0 \
    --definition-id openapi --file-name "/Path/to/specificationFile.json"

Register API from a specification file - single step

You can register an API from a local specification file in a single step by using the az apic api register command. With this option, a default API version and definition are created automatically for the API.

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

az apic api register --resource-group myResourceGroup \
    --service myAPICenter --api-location "/Path/to/specificationFile.json"

• The command sets the API properties such as name and type from values in the definition file.
• By default, the command sets the API's Lifecycle stage to design.
• It creates a default API version named 1-0-0 and a default definition named according to the specification format (for example, openapi).

After registering an API, you can update the API's properties by using the az apic api update, az apic api version update, and az apic api definition update commands.

Delete API resources

Use the az apic api delete command to delete an API and all of its version and definition resources. For example:

az apic api delete \
    --resource-group myResoureGroup --service myAPICenter \
    --api-id petstore-api

To delete individual API versions and definitions, use az apic api version delete and az apic api definition delete, respectively.

Related content

• See the Azure CLI reference for Azure API Center for a complete command list, including commands to manage environments, deployments, metadata schemas, and services.
• Import APIs to your API center from API Management
• Use the Visual Studio extension for API Center to build and register APIs from Visual Studio Code.