Microsoft Azure API Management Client Library for Python

Common errors

• HttpResponseError: (MissingOrIncorrectVersionParameter) API version query parameter is not specified or was specified incorrectly. Supported versions: ...

  cause This error occurs when the Azure API Management service does not receive a valid API version parameter in the request, or the version implicitly or explicitly specified by the SDK is not supported by the service endpoint, possibly due to a breaking change in the API or a bug in a specific SDK version (e.g., 5.0.0 for `ProductOperations.create_or_update`).
  fix Ensure you are using the latest stable version of the `azure-mgmt-apimanagement` library. If the issue persists with a specific operation after a version upgrade, check the official Azure SDK for Python GitHub issues for known regressions or specific parameter requirements for the affected method. In some cases, adjusting the parameters as per new API definitions might be necessary.

• HttpResponseError: (AuthorizationFailed) The client 'xxxxxxxxxxxxxxxxxxxxxxxxxxx' with object id 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' does not have authorization to perform action 'Microsoft.ApiManagement/service/apis/write' over scope '...' or the scope is invalid. If access was recently granted, please refresh your credentials."

  cause The Azure Active Directory (AAD) principal (user, service principal, or managed identity) used to authenticate the `ApiManagementClient` lacks the necessary Azure RBAC permissions to perform the requested management operation on the specified Azure API Management resource.
  fix Grant the AAD principal the appropriate Azure RBAC role (e.g., 'API Management Contributor' or a custom role with the required permissions like `Microsoft.ApiManagement/service/apis/write`) at the correct scope (e.g., resource group or the specific API Management service instance). Ensure credentials are up-to-date and, if using `DefaultAzureCredential`, that environment variables or other authentication sources are correctly configured.

• HttpResponseError: (ResourceNotFound) Api not found.

  cause This error indicates that the specific API Management resource (e.g., an API, product, policy, or diagnostic) you are attempting to access, update, or delete does not exist at the specified path or with the provided identifier. This can be due to typos, incorrect resource IDs, or attempting to operate on a resource that has not yet been created.
  fix Verify that the resource name, ID, and resource group name are accurate and that the target resource actually exists in your Azure subscription. If the resource is dynamically created, ensure that its creation process has completed successfully before attempting subsequent operations on it.

• HttpResponseError: (Conflict) API with specified name already exists.

  cause You are attempting to create an API (or another resource like a product) with a name that is already in use within the target Azure API Management service instance. This error can also be misleadingly triggered by underlying issues in an imported API definition, such as duplicate operation IDs within an OpenAPI (Swagger) specification.
  fix Use a unique name for the API or resource you are creating. If importing an OpenAPI definition, ensure it is valid and does not contain duplicate operation IDs or other conflicting definitions. Review the backend API definition for any inconsistencies that might cause conflicts during the import process.

Warnings

• breaking Starting June 1, 2024, all Azure API Management service API versions prior to 2021-08-01 are being retired (disabled). Management operations (creation, update, etc.) using older API versions via this SDK will fail. Data plane operations (API gateway) are unaffected. [23]
  Fix: Update `azure-mgmt-apimanagement` to version 3.0.0 or later and ensure your calls target API version 2021-08-01 or later in your service definitions or client initialization. [23]
• breaking Trusted service connectivity in API Management gateway will be retired on March 15, 2026. Review Azure guidance to determine if your API Management service is affected. [12]
  Fix: Consult Azure documentation for migration guidance related to trusted service connectivity retirement. [12]
• gotcha `DefaultAzureCredential` relies on specific environment variables (`AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_SUBSCRIPTION_ID`) for token authentication. Misconfiguration of these variables is a common source of authorization errors. [1, 2, 7]
  Fix: Ensure `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_SECRET`, and `AZURE_SUBSCRIPTION_ID` environment variables are correctly set for `DefaultAzureCredential` to function. [1, 2, 7]
• breaking Version 5.0.0 introduced several new operation groups (e.g., `api_gateway`, `api_management_gateway_skus`, `all_policies`). Existing code interacting with these areas in previous versions may require updates to use the new client methods and structures. [1]
  Fix: Review the release notes for version 5.0.0 and update client calls to leverage the new operation groups and their methods where applicable. [1]

Install

• pip install azure-mgmt-apimanagement azure-identity Install package and authentication library

Imports

• ApiManagementClient

  from azure.mgmt.apimanagement import ApiManagementClient

• DefaultAzureCredential

  from azure.identity import DefaultAzureCredential

Quickstart

Initializes the `ApiManagementClient` using `DefaultAzureCredential` and lists all API Management services within the specified Azure subscription. Ensure your Azure authentication environment variables (AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET) and AZURE_SUBSCRIPTION_ID are set for `DefaultAzureCredential` to work correctly. [1, 2, 7]

import os
from azure.identity import DefaultAzureCredential
from azure.mgmt.apimanagement import ApiManagementClient

# Set environment variables or replace with your actual values
# AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET must be set for DefaultAzureCredential
# AZURE_SUBSCRIPTION_ID is also required for the client
subscription_id = os.environ.get('AZURE_SUBSCRIPTION_ID', 'YOUR_SUBSCRIPTION_ID')

# Authenticate and create API Management client
try:
    credential = DefaultAzureCredential()
    client = ApiManagementClient(credential, subscription_id)
    print(f"Successfully authenticated for subscription: {subscription_id}")

    # List all API Management services in the subscription
    print("Listing API Management services...")
    for service in client.api_management_service.list():
        print(f"  - Name: {service.name}, Location: {service.location}, SKU: {service.sku.name}")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Please ensure AZURE_SUBSCRIPTION_ID and Azure authentication environment variables (AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET) are correctly set.")