azure-mgmt-apicenter-py

Azure API Center Management SDK for Python

Manage API inventory, metadata, and governance in Azure API Center.

Installation

pip install azure-mgmt-apicenter
pip install azure-identity

Environment Variables

AZURE_SUBSCRIPTION_ID=your-subscription-id  # Required for all auth methods
AZURE_TOKEN_CREDENTIALS=prod # Required only if DefaultAzureCredential is used in production

Authentication & Lifecycle

🔑 Two rules apply to every code sample below:

1. Prefer DefaultAzureCredential. It works locally (Azure CLI / VS Code / Developer CLI) and in Azure (managed identity, workload identity) with no code change. Avoid connection strings, account/API keys — they bypass Entra audit and rotation.
   • Local dev: DefaultAzureCredential works as-is.
   • Production: set AZURE_TOKEN_CREDENTIALS=prod (or AZURE_TOKEN_CREDENTIALS=<specific_credential>) to constrain the credential chain to production-safe credentials.
2. Wrap every client in a context manager so HTTP transports, sockets, and token caches are released deterministically:
   • Sync: with <Client>(...) as client:
   • Async: async with <Client>(...) as client: and async with DefaultAzureCredential() as credential: (from azure.identity.aio)

Snippets may abbreviate this setup, but production code should always follow both rules.

from azure.identity import DefaultAzureCredential, ManagedIdentityCredential
from azure.mgmt.apicenter import ApiCenterMgmtClient
import os

# Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=<specific_credential>
credential = DefaultAzureCredential(require_envvar=True)
# Or use a specific credential directly in production:
# See https://learn.microsoft.com/python/api/overview/azure/identity-readme?view=azure-python#credential-classes
# credential = ManagedIdentityCredential()

with ApiCenterMgmtClient(
    credential=credential,
    subscription_id=os.environ["AZURE_SUBSCRIPTION_ID"]
) as client:
    # Use `client` for all subsequent operations (see examples below)
    ...

Create API Center

from azure.mgmt.apicenter.models import Service

api_center = client.services.create_or_update(
    resource_group_name="my-resource-group",
    service_name="my-api-center",
    resource=Service(
        location="eastus",
        tags={"environment": "production"}
    )
)

print(f"Created API Center: {api_center.name}")

List API Centers

api_centers = client.services.list_by_subscription()

for api_center in api_centers:
    print(f"{api_center.name} - {api_center.location}")

Register an API

from azure.mgmt.apicenter.models import Api, ApiKind, ApiProperties

api = client.apis.create_or_update(
    resource_group_name="my-resource-group",
    service_name="my-api-center",
    workspace_name="default",
    api_name="my-api",
    resource=Api(
        properties=ApiProperties(
            title="My API",
            description="A sample API for demonstration",
            kind=ApiKind.REST,
            terms_of_service={"url": "https://example.com/terms"},
            contacts=[{"name": "API Team", "email": "api-team@example.com"}],
        )
    ),
)

print(f"Registered API: {api.properties.title}")

Create API Version

from azure.mgmt.apicenter.models import ApiVersion, ApiVersionProperties, LifecycleStage

version = client.api_versions.create_or_update(
    resource_group_name="my-resource-group",
    service_name="my-api-center",
    workspace_name="default",
    api_name="my-api",
    version_name="v1",
    resource=ApiVersion(
        properties=ApiVersionProperties(
            title="Version 1.0",
            lifecycle_stage=LifecycleStage.PRODUCTION,
        )
    ),
)

print(f"Created version: {version.properties.title}")

Add API Definition

from azure.mgmt.apicenter.models import ApiDefinition, ApiDefinitionProperties

definition = client.api_definitions.create_or_update(
    resource_group_name="my-resource-group",
    service_name="my-api-center",
    workspace_name="default",
    api_name="my-api",
    version_name="v1",
    definition_name="openapi",
    resource=ApiDefinition(
        properties=ApiDefinitionProperties(
            title="OpenAPI Definition",
            description="OpenAPI 3.0 specification",
        )
    ),
)

Import API Specification

from azure.mgmt.apicenter.models import ApiSpecImportRequest, ApiSpecImportSourceFormat

# Import from inline content
client.api_definitions.begin_import_specification(
    resource_group_name="my-resource-group",
    service_name="my-api-center",
    workspace_name="default",
    api_name="my-api",
    version_name="v1",
    definition_name="openapi",
    body=ApiSpecImportRequest(
        format=ApiSpecImportSourceFormat.INLINE,
        value='{"openapi": "3.0.0", "info": {"title": "My API", "version": "1.0"}, "paths": {}}',
    )
).result()

List APIs

apis = client.apis.list(
    resource_group_name="my-resource-group",
    service_name="my-api-center",
    workspace_name="default"
)

for api in apis:
    print(f"{api.name}: {api.title} ({api.kind})")

Create Environment

from azure.mgmt.apicenter.models import Environment, EnvironmentKind, EnvironmentProperties

environment = client.environments.create_or_update(
    resource_group_name="my-resource-group",
    service_name="my-api-center",
    workspace_name="default",
    environment_name="production",
    resource=Environment(
        properties=EnvironmentProperties(
            title="Production",
            description="Production environment",
            kind=EnvironmentKind.PRODUCTION,
            server={"type": "Azure API Management", "management_portal_uri": ["https://portal.azure.com"]},
        )
    ),
)

Create Deployment

from azure.mgmt.apicenter.models import Deployment, DeploymentProperties, DeploymentState

deployment = client.deployments.create_or_update(
    resource_group_name="my-resource-group",
    service_name="my-api-center",
    workspace_name="default",
    api_name="my-api",
    deployment_name="prod-deployment",
    resource=Deployment(
        properties=DeploymentProperties(
            title="Production Deployment",
            description="Deployed to production APIM",
            environment_id="/workspaces/default/environments/production",
            definition_id="/workspaces/default/apis/my-api/versions/v1/definitions/openapi",
            state=DeploymentState.ACTIVE,
            server={"runtime_uri": ["https://api.example.com"]},
        )
    ),
)

Define Custom Metadata

from azure.mgmt.apicenter.models import MetadataSchema, MetadataSchemaProperties

metadata = client.metadata_schemas.create_or_update(
    resource_group_name="my-resource-group",
    service_name="my-api-center",
    metadata_schema_name="data-classification",
    resource=MetadataSchema(
        properties=MetadataSchemaProperties(
            schema='{"type": "string", "title": "Data Classification", "enum": ["public", "internal", "confidential"]}'
        )
    ),
)

Client Types

Operations

Best Practices

1. Pick sync OR async and stay consistent. Do not mix azure.xxx sync clients with azure.xxx.aio async clients in the same call path. Choose one mode per module.
2. Always use context managers for clients and async credentials. Wrap every client in with Client(...) as client: (sync) or async with Client(...) as client: (async). For async DefaultAzureCredential from azure.identity.aio, also use async with credential: so tokens and transports are cleaned up.
3. Use workspaces to organize APIs by team or domain
4. Define metadata schemas for consistent governance
5. Track deployments to understand where APIs are running
6. Import specifications to enable API analysis and linting
7. Use lifecycle stages to track API maturity
8. Add contacts for API ownership and support

Reference Files