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.

• 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 Get started with 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 Authenticate to Azure using Azure CLI.

    • When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see Use and manage 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. Certain features may require a preview or specific version of the extension.

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.

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-name myAPICenter --api-id petstore-api \
    --title "Petstore API" --type "rest"

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-name myAPICenter --api-id petstore-api \
    --version-id v1-0-0 --title "v1-0-0" --lifecycle-stage "testing"

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

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-name myAPICenter --api-id petstore-api \
    --version-id v1-0-0 --definition-id openapi --title "OpenAPI"

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-name 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"}'

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-name myAPICenter \
    --api-id petstore-api --version-id v1-0-0 \
    --definition-id openapi --file-name "/Path/to/specificationFile.json"

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-name 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 an API version named according to the version property in the API definition (or 1-0-0 by default), and an API 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.

The following example updates the title of the petstore-api API to Petstore API v2.

az apic api update --resource-group myResourceGroup \
    --service-name myAPICenter --api-id petstore-api \
    --title "Petstore API v2"

The following example sets the API's Boolean internal custom property to false.

az apic api update --resource-group myResourceGroup \
    --service-name myAPICenter --api-id petstore-api \
    --set custom_properties.internal=false

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

• 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.
• Register APIs in your API center using GitHub Actions