Skill v1.0.1

currentAutomated scan100/100

azure-samples/apim-samples/apim-bicep

+2 new

──Details

PublishedAugust 15, 2026 at 01:16 AM

Content Hashsha256:e6fa8c8b59bfc7d0...

Git SHA4aee2e38b38a

Bump Typepatch

Compare with v1.0.0

──Files

Files (1 file, 7.9 KB)

SKILL.md7.9 KBactive

SKILL.md · 275 lines · 7.9 KB

version: "1.0.1" name: apim-bicep description: Guide for building Bicep files for Azure API Management (APIM) and related Azure services. Use when users want to create, modify, or understand Bicep templates for APIM instances, APIs, backends, subscriptions, policies, products, loggers, and diagnostics. This skill provides Bicep syntax and patterns based on the shared modules in this repository.

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 seven-day release waiting period. Any new dependency must use an eligible exact version and the repository's guarded install flow.

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

bicep

@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

Resource Type	API Version	Purpose
`Microsoft.ApiManagement/service`	`2024-06-01-preview`	APIM service instance
`Microsoft.ApiManagement/service/apis`	`2024-06-01-preview`	API definitions
`Microsoft.ApiManagement/service/apis/operations`	`2024-06-01-preview`	API operations
`Microsoft.ApiManagement/service/apis/policies`	`2024-06-01-preview`	API-level policies
`Microsoft.ApiManagement/service/backends`	`2024-06-01-preview`	Backend services
`Microsoft.ApiManagement/service/subscriptions`	`2024-06-01-preview`	API subscriptions
`Microsoft.ApiManagement/service/products`	`2024-06-01-preview`	API products
`Microsoft.ApiManagement/service/loggers`	`2024-06-01-preview`	Logging configuration
`Microsoft.ApiManagement/service/apis/diagnostics`	`2024-06-01-preview`	API diagnostics

Essential Patterns

Backend with Managed Identity

bicep

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)

bicep

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

bicep

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

bicep

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

Subscription

bicep

@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

Azure Monitor Logger

bicep

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

Application Insights Logger

bicep

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

bicep

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

bicep

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

Parameter Validation

bicep

@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

bicep

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

bicep

#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

← v1.0.0 All versions