APIM Bicep

This skill provides guidance for creating Azure Bicep templates for API Management and related services.

Do not add tool, module, CLI extension, container feature, or package installation that bypasses the repository's eight-day release waiting period. Any new dependency must use an eligible exact version and the repository's guarded install flow.

MockAPI container images from simonkurtzmsft/mockapi are exempt from this waiting period. Keep an exact version tag and immutable digest; this exception does not apply to packages, tools, or GitHub Actions.

When this workflow creates or updates Markdown, follow .markdownlint.json and .github/markdown.instructions.md without flattening semantic structure. Before completion, run npx --no-install markdownlint-cli2 "**/*.md" "#**/.venv/**" "#**/node_modules/**" from the repository root and require zero violations.

Quick Start - Basic APIM Instance

@description('The name of the API Management service instance')
param apiManagementServiceName string = 'apim-${uniqueString(resourceGroup().id)}'

@description('The email address of the publisher')
param publisherEmail string

@description('The name of the publisher')
param publisherName string

@description('The pricing tier of this API Management service')
@allowed(['Consumption', 'Developer', 'Basic', 'Basicv2', 'Standard', 'Standardv2', 'Premium', 'Premiumv2'])
param sku string = 'Basicv2'

@description('Location for all resources')
param location string = resourceGroup().location

resource apimService 'Microsoft.ApiManagement/service@2024-06-01-preview' = {
  name: apiManagementServiceName
  location: location
  sku: {
    name: sku
    capacity: 1
  }
  identity: {
    type: 'SystemAssigned'
  }
  properties: {
    publisherEmail: publisherEmail
    publisherName: publisherName
  }
}

output apimId string = apimService.id
output apimName string = apimService.name
output gatewayUrl string = apimService.properties.gatewayUrl
output principalId string = apimService.identity.principalId

Resource Types Reference

Essential Patterns

Backend with Managed Identity

resource backend 'Microsoft.ApiManagement/service/backends@2024-06-01-preview' = {
  name: 'my-backend'
  parent: apimService
  properties: {
    description: 'Backend with managed identity auth'
    url: 'https://my-service.azure.com'
    protocol: 'http'
    credentials: {
      managedIdentity: {
        resource: 'https://cognitiveservices.azure.com'
      }
    }
  }
}

Backend Pool (Load Balancing)

resource backendPool 'Microsoft.ApiManagement/service/backends@2024-06-01-preview' = {
  name: 'inference-backend-pool'
  parent: apimService
  properties: {
    description: 'Load balancer for multiple backends'
    type: 'Pool'
    pool: {
      services: [for (config, i) in backendsConfig: {
        id: '/backends/${backends[i].name}'
        priority: config.?priority ?? 1
        weight: config.?weight ?? 1
      }]
    }
  }
}

API with OpenAPI Spec

resource api 'Microsoft.ApiManagement/service/apis@2024-06-01-preview' = {
  name: 'my-api'
  parent: apimService
  properties: {
    displayName: 'My API'
    description: 'API description'
    path: 'api/v1'
    protocols: ['https']
    subscriptionRequired: true
    subscriptionKeyParameterNames: {
      header: 'api-key'
      query: 'api-key'
    }
    format: 'openapi+json'
    value: string(loadJsonContent('./openapi.json'))
  }
}

API Policy from File

resource apiPolicy 'Microsoft.ApiManagement/service/apis/policies@2024-06-01-preview' = {
  name: 'policy'
  parent: api
  properties: {
    format: 'rawxml'
    value: loadTextContent('policy.xml')
  }
}

Subscription

@batchSize(1)
resource subscription 'Microsoft.ApiManagement/service/subscriptions@2024-06-01-preview' = [for sub in subscriptionsConfig: {
  name: sub.name
  parent: apimService
  properties: {
    displayName: sub.displayName
    scope: '/apis'  // or '/apis/{apiId}' or '/products/{productId}'
    state: 'active'
    allowTracing: true
  }
}]

Diagnostics and Logging

Diagnostic Setting Ownership

• Each infrastructure owns one canonical apim-diagnostics setting for its APIM service and Log Analytics workspace.
• Enable GatewayLogs, WebSocketConnectionLogs, and GatewayLlmLogs in that shared setting so samples can coexist without redefining category-to-sink mappings.
• Samples that need the infrastructure workspace must reuse the canonical setting name. Do not create a sample-named setting for the same workspace and categories.
• A sample-specific diagnostic setting is valid only for a different sink, such as Event Hub. Keep that setting destination-specific so later baseline deployments cannot remove its configuration.
• Run legacy diagnostic-setting migration before every infrastructure deployment, not only when an update flag is set. Create and retry paths can target existing resources; test both paths and stop deployment if migration fails.
• Azure can restore orphaned diagnostic settings after a deleted APIM resource is recreated, when preflight discovery found nothing. After a failed infrastructure deployment, rerun migration and retry once only if it removed a legacy setting. Test reappearance after empty preflight, no-op recovery, migration failure, and the retry limit.

Azure Monitor Logger

resource apimLogger 'Microsoft.ApiManagement/service/loggers@2024-06-01-preview' = {
  parent: apimService
  name: 'azuremonitor'
  properties: {
    loggerType: 'azureMonitor'
    isBuffered: false
  }
}

Application Insights Logger

resource appInsightsLogger 'Microsoft.ApiManagement/service/loggers@2024-06-01-preview' = {
  name: 'appinsights-logger'
  parent: apimService
  properties: {
    loggerType: 'applicationInsights'
    credentials: {
      instrumentationKey: appInsightsInstrumentationKey
    }
    description: 'APIM Logger for Application Insights'
    isBuffered: false
    resourceId: appInsightsId
  }
}

API Diagnostics with LLM Logging

resource apiDiagnostics 'Microsoft.ApiManagement/service/apis/diagnostics@2024-06-01-preview' = {
  parent: api
  name: 'azuremonitor'
  properties: {
    alwaysLog: 'allErrors'
    verbosity: 'verbose'
    logClientIp: true
    loggerId: apimLogger.id
    sampling: {
      samplingType: 'fixed'
      percentage: 100
    }
    largeLanguageModel: {
      logs: 'enabled'
      requests: {
        messages: 'all'
        maxSizeInBytes: 262144
      }
      responses: {
        messages: 'all'
        maxSizeInBytes: 262144
      }
    }
  }
}

Bicep Best Practices

Use Existing Resources

resource apim 'Microsoft.ApiManagement/service@2024-06-01-preview' existing = {
  name: apimServiceName
}

Parameter Validation

@description('The pricing tier')
@allowed(['Consumption', 'Developer', 'Basic', 'Basicv2', 'Standard', 'Standardv2', 'Premium', 'Premiumv2'])
param sku string = 'Basicv2'

@minLength(1)
@maxLength(50)
param apiManagementName string

Load External Content

// Load JSON for OpenAPI specs
value: string(loadJsonContent('./specs/openapi.json'))

// Load XML for policies
value: loadTextContent('policy.xml')

// Load and parameterize policy
var updatedPolicy = replace(loadTextContent('policy.xml'), '{backend-id}', backendName)

Output Secrets Safely

#disable-next-line outputs-should-not-contain-secrets
output subscriptionKey string = subscription.listSecrets().primaryKey

Reference Documentation

• Shared modules in this repo: shared/bicep/modules/apim/v1/ (api, apim, backend, backend-pool, diagnostics, named-value, policy-fragment, product)

Official Documentation

• APIM Bicep Quickstart
• ARM Template Reference