Use the Azure CLI to manage your API inventory

  • Article

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:

    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.

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

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

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

Related content