Introduction to Azure API Management

BeginnerAPI Management2026-03-14

What Is Azure API Management?

Azure API Management (APIM) is a fully managed service that helps organisations publish, secure, transform, maintain, and monitor APIs. It acts as a gateway between your API consumers and your backend services.

Official Documentation: Azure API Management overview

Core Components

API Gateway

The runtime component that processes API calls, applies policies, and routes requests to backends. Key capabilities:

Request routing — Route API calls to the correct backend service
Policy enforcement — Apply authentication, rate limiting, transformation, and caching
Protocol translation — Convert between REST, SOAP, WebSocket, and GraphQL
Load balancing — Distribute requests across multiple backend instances
SSL/TLS termination — Handle certificate management at the gateway

Developer Portal

An automatically generated, fully customisable website where developers can:

Discover and explore available APIs
Read interactive API documentation
Try APIs directly in the browser (Test Console)
Obtain and manage subscription keys
View usage analytics and quotas

Microsoft Reference: Developer portal overview

Management Plane

The Azure Portal interface (or REST API / Bicep / Terraform) used to configure:

APIs and operations
Policies at all scopes
Products and subscriptions
Users, groups, and access control
Named Values and backends
Diagnostics and logging

Key Concepts

Concept	Description
APIs	Definitions of your API surface area (operations, request/response schemas)
Operations	Individual endpoints within an API (GET /orders, POST /orders, etc.)
Products	Bundles of APIs offered to developers — Open (no subscription required) or Protected (subscription key required)
Subscriptions	Keys that grant access to products or individual APIs
Policies	XML-based rules applied at inbound, backend, outbound, or on-error stages
Named Values	Key-value pairs for storing configuration (can reference Key Vault secrets)
Backends	Backend service definitions with load balancing, circuit breaking, and credential management
Groups	Logical groupings of users for access control (Administrators, Developers, Guests)
Tags	Labels for organising APIs and products
Revisions	Non-breaking changes to an API (like draft versions)
Versions	Breaking changes published as separate API versions (v1, v2)
Workspaces	Decentralised API management for different teams (Premium tier)

API Import Formats

Format	Description
OpenAPI (Swagger)	REST API definitions in JSON or YAML
WSDL	SOAP service definitions
WADL	RESTful service definitions
GraphQL	GraphQL schema definitions
Azure Compute	Import from App Service, Function App, Logic App, or Container App
Manual	Define operations manually in the portal

Microsoft Reference: Import and publish your first API

Choosing a Tier

Tier	Use Case	SLA	VNET	Multi-Region	Self-Hosted GW	Cache
Consumption	Serverless, pay-per-call	99.95%	No	No	No	External only
Developer	Testing and development	No SLA	Yes	No	Yes	Built-in
Basic	Entry-level production	99.95%	No	No	No	Built-in
Standard	Medium-scale production	99.95%	No	No	Yes	Built-in
Premium	Enterprise, multi-region	99.99%	Yes	Yes	Yes	Built-in
Basic v2	New generation basic	99.95%	Yes	No	No	External only
Standard v2	New generation standard	99.95%	Yes	No	Yes	External only

Tier Selection Guide

Proof of concept / Development → Developer (full features, no SLA)
Small API programme (<1000 calls/min) → Basic or Basic v2
Medium API programme → Standard or Standard v2
Enterprise with VNET requirements → Premium or Standard v2
Multi-region HA → Premium
Serverless / low volume → Consumption
Event-driven APIs → Consumption

Microsoft Reference: Feature comparison by tier

Pricing Overview

Tier	Approximate Monthly Cost
Consumption	~£2.80 per million calls
Developer	~£40/month
Basic	~£120/month
Standard	~£540/month
Premium	~£2,200/month (per unit)

Microsoft Reference: API Management pricing

Creating Your First APIM Instance

Via Azure Portal

Navigate to Create a Resource → Integration → API Management
Select your tier (Developer for testing, Standard for production)
Configure: subscription, resource group, name, region, and organisation name
Set up an administrator email for notifications
Wait for provisioning (Developer tier takes ~30–45 minutes; v2 tiers are faster)
Once deployed, import your first API

Via Azure CLI

# Create an APIM instance
az apim create \
  --name apim-enterprise-dev \
  --resource-group rg-integration-dev \
  --location uksouth \
  --publisher-name "Enterprise Ltd" \
  --publisher-email admin@enterprise.com \
  --sku-name Developer \
  --sku-capacity 1

# Import an OpenAPI specification
az apim api import \
  --resource-group rg-integration-dev \
  --service-name apim-enterprise-dev \
  --api-id orders-api \
  --path orders \
  --specification-format OpenApi \
  --specification-url https://api.example.com/swagger.json \
  --display-name "Orders API"

Via Bicep

param location string = resourceGroup().location
param environment string

resource apim 'Microsoft.ApiManagement/service@2023-05-01-preview' = {
  name: 'apim-enterprise-${environment}'
  location: location
  sku: {
    name: environment == 'prod' ? 'Standard' : 'Developer'
    capacity: 1
  }
  identity: {
    type: 'SystemAssigned'
  }
  properties: {
    publisherEmail: 'api-admin@enterprise.com'
    publisherName: 'Enterprise Ltd'
    customProperties: {
      'Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Protocols.Tls10': 'False'
      'Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Protocols.Tls11': 'False'
      'Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Tls10': 'False'
      'Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Tls11': 'False'
    }
  }
}

// Import an API
resource ordersApi 'Microsoft.ApiManagement/service/apis@2023-05-01-preview' = {
  parent: apim
  name: 'orders-api'
  properties: {
    displayName: 'Orders API'
    path: 'orders'
    protocols: ['https']
    subscriptionRequired: true
    format: 'openapi+json'
    value: loadTextContent('api-specs/orders-api.json')
  }
}

// Create a Product
resource product 'Microsoft.ApiManagement/service/products@2023-05-01-preview' = {
  parent: apim
  name: 'standard-product'
  properties: {
    displayName: 'Standard Product'
    description: 'Access to standard API operations'
    subscriptionRequired: true
    approvalRequired: true
    state: 'published'
  }
}

// Link API to Product
resource productApi 'Microsoft.ApiManagement/service/products/apis@2023-05-01-preview' = {
  parent: product
  name: ordersApi.name
}

Testing Your API

Built-in Test Console

Navigate to your API in the portal
Select an operation
Click the Test tab
Add required parameters and headers
Click Send to execute the request
Review the response, including headers and status code

Using curl

# Call your API through the APIM gateway
curl -X GET "https://apim-enterprise-dev.azure-api.net/orders" \
  -H "Ocp-Apim-Subscription-Key: your-subscription-key" \
  -H "Accept: application/json"

API Diagnostics

Enable diagnostics to capture request/response details:

resource apiDiagnostic 'Microsoft.ApiManagement/service/apis/diagnostics@2023-05-01-preview' = {
  parent: ordersApi
  name: 'applicationinsights'
  properties: {
    loggerId: '/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.ApiManagement/service/{apim}/loggers/{logger}'
    sampling: {
      samplingType: 'fixed'
      percentage: 100
    }
    frontend: {
      request: {
        headers: ['X-Correlation-Id']
        body: { bytes: 1024 }
      }
      response: {
        headers: ['Content-Type']
        body: { bytes: 1024 }
      }
    }
    backend: {
      request: {
        headers: ['Authorization']
        body: { bytes: 1024 }
      }
      response: {
        body: { bytes: 1024 }
      }
    }
  }
}

Naming Conventions

Follow the Cloud Adoption Framework:

apim-{workload}-{environment}

Examples:

apim-enterprise-dev
apim-partner-portal-prod