Azure API Management (APIM)

Key Points

• APIM is Azure's API gateway. Sits between consumers and your backends. Authentication, throttling, transformation, analytics, developer portal.
• Tiers: Consumption (serverless, pay-per-use), Developer (no SLA, dev only), Basic/Standard/Premium (always-on), Premium (vnet, multi-region).
• Policies = XML-based pipeline transformations. Validate JWT, rate limit, transform, retry, cache.
• Products group APIs; Subscriptions are API keys; Developer portal for self-service onboarding.
• 2026 alternatives: YARP for in-app gateway; Azure Front Door for global L7.

Concepts (deep dive)

What APIM is

APIM is a managed API gateway plus a developer experience. The gateway part is the runtime: every external request to your APIs flows through APIM, where a configurable pipeline of policies (XML snippets) handles cross-cutting concerns — JWT validation, rate limiting, schema validation, transformation, caching, mocking — before the request ever reaches your backend. The developer experience part is the portal, the product/subscription model, and the analytics — the things that turn "an API exists" into "an API has consumers, governance, and a self-service onboarding flow."

   ┌─────────────────────────────────────────────────────────────┐
   │                       APIM gateway                          │
   │                                                             │
   │   inbound  ─►  backend  ─►  outbound  ─►  on-error          │
   │      │           │            │              │              │
   │   - JWT       - retry      - strip       - friendly         │
   │   - rate-     - circuit    - response       error           │
   │     limit       breaker      headers       shape            │
   │   - quota                  - cache-                         │
   │   - transform                store                          │
   │   - cache-                                                  │
   │     lookup                                                  │
   └─────────────────────────────────────────────────────────────┘
            ▲                                          │
            │                                          ▼
       Consumer                                  Backend(s)
       (web, mobile,                             (App Service, Container
        partner)                                  Apps, Functions, AKS,
                                                  on-prem via VNet)
   ──────────────────────────────────────────────────────────────
       Side products of the gateway sitting on top:
       - Products (groupings of APIs)
       - Subscriptions (API keys, scoped to products)
       - Developer portal (self-service onboarding)
       - Analytics (per-API, per-product, per-subscription)

Why have a gateway at all instead of putting auth and rate-limit in each service? Because every backend would otherwise re-implement the same six things — and worse, slightly differently each time. The gateway centralizes the policy layer so the backends only own business logic. The price is one more network hop and one more thing to operate.

Topology

Consumer → APIM → Backend(s)
            policies (auth, rate, transform)
            developer portal
            analytics

Policies (XML pipeline)

A policy is a small XML element that runs at one of four stages of the request lifecycle: inbound (before forwarding to backend), backend (around the actual call), outbound (after backend response, before client), on-error (whenever an exception escapes). Policies compose top-to-bottom within a stage. <base /> includes the policy chain inherited from a higher scope (global → product → API → operation), so a global policy can be selectively augmented or overridden at narrower scopes.

<policies>
  <inbound>
    <base />
    <validate-jwt header-name="Authorization">
      <openid-config url="https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration" />
      <required-claims>
        <claim name="aud"><value>api://my-api</value></claim>
      </required-claims>
    </validate-jwt>
    <rate-limit calls="100" renewal-period="60" />
    <set-header name="X-Forwarded-For" exists-action="override">
      <value>@(context.Request.IpAddress)</value>
    </set-header>
  </inbound>
  <backend><base /></backend>
  <outbound>
    <base />
    <set-header name="X-Powered-By" exists-action="delete" />
  </outbound>
  <on-error>
    <base />
    <set-status code="500" reason="Server Error" />
  </on-error>
</policies>

Stages: inbound → backend → outbound → on-error.

Common policies

Tiers

For 2026, Consumption tier is great for cost-sensitive workloads. Premium for enterprise.

Products + Subscriptions

Product: "Free Tier"
  ├── API: "Orders"
  └── API: "Inventory"
Subscription: API key tied to a product → consumer uses it

Developer portal

Auto-generated docs + try-it-out. Companies expose to external developers — onboarding, generating subscription keys.

OpenAPI import

Import OpenAPI spec → APIM creates API endpoints. Re-import on changes; APIM keeps in sync.

az apim api import --resource-group rg --service-name myapim \
  --path orders --specification-format OpenApi \
  --specification-path openapi.json

Versioning

• Path: /v1/orders, /v2/orders.
• Header: X-Api-Version: 2.
• Query: ?api-version=2.

APIM supports all three. Prefer header or path.

Authentication patterns

• Subscription key (header Ocp-Apim-Subscription-Key).
• JWT validation: validate-jwt policy.
• OAuth2: validate-azure-ad-token.
• Client cert: validate-client-certificate.

Layer: subscription key + JWT.

Rate limiting

<rate-limit-by-key calls="100" renewal-period="60"
                  counter-key="@(context.Subscription.Id)" />
<quota-by-key calls="100000" renewal-period="2592000"
              counter-key="@(context.Subscription.Id)" />

Per-subscription, per-IP, per-user. Renewal periods.

Caching

<cache-lookup vary-by-developer="false" vary-by-developer-groups="false">
  <vary-by-header>Accept</vary-by-header>
</cache-lookup>

External Redis or built-in.

Backends

Multiple backends per API. Failover, weighted routing.

Multi-region (Premium)

Active-active across regions. Auto-failover.

Self-hosted gateway

Premium tier. Run APIM gateway component on-prem / k8s. Backends stay local; control plane in Azure.

When APIM vs YARP

Cost

Premium is expensive ($2K+/month). Consumption is consumption-based.

For lots of internal services: prefer YARP / Front Door / Application Gateway.

Code: correct vs wrong

❌ Wrong: APIM as service-to-service router

Heavy for internal traffic.

✅ Correct: APIM for external; YARP/internal LB for internal

External → APIM (auth, rate, monetization) → Internal services
Internal A → YARP/LB → Internal B

❌ Wrong: subscription key as only auth

<!-- Just keys; anyone can use stolen key -->

✅ Correct: layered auth

<validate-jwt /> <rate-limit-by-key />

Design patterns for this topic

Pattern 1 — "APIM for external APIs"

• Intent: managed gateway with portal.

Pattern 2 — "Layered auth: subscription + JWT"

• Intent: defense in depth.

Pattern 3 — "Versioning strategy"

• Intent: clear v1/v2 split.

Pattern 4 — "Backend caching for hot reads"

• Intent: offload backends.

Pattern 5 — "Multi-region for HA"

• Intent: Premium; auto-failover.

Pros & cons / trade-offs

When to use / when to avoid

• Use for external/customer-facing APIs needing developer portal.
• Use Consumption tier for low-volume.
• Avoid for internal-only routing.
• Avoid Premium unless you need VNet/multi-region.

Interview Q&A

Q1. APIM tiers? Consumption, Developer, Basic, Standard, Premium. Consumption: serverless. Premium: vnet/multi-region.

Q2. Policy stages? inbound → backend → outbound → on-error.

Q3. Common policies? validate-jwt, rate-limit, cache-lookup/store, set-header, retry.

Q4. Products + subscriptions? Product = collection of APIs. Subscription = API key tied to a product.

Q5. Developer portal? Self-service docs + signup. Generates subscription keys.

Q6. Versioning options? Path, header, query. APIM supports all.

Q7. APIM vs YARP? APIM: managed, external, portal, monetization. YARP: in-app, .NET-native, internal.

Q8. Self-hosted gateway? Premium feature. Runs gateway component on-prem; control plane in Azure.

Q9. Caching? External Redis or built-in. Vary by header/query.

Q10. Subscription key alone enough? No — pair with JWT. Stolen key without auth = access.

Q11. OpenAPI import? APIM auto-generates endpoints from spec. Sync on update.

Q12. Premium why? VNet, multi-region active-active, self-hosted gateway, higher SLA.

Gotchas / common mistakes

• ⚠️ Subscription key as only auth.
• ⚠️ Premium when Consumption suffices.
• ⚠️ No rate limit — abuse risk.
• ⚠️ Weak token validation in policy.
• ⚠️ APIM for internal routing — overkill.

Further reading

• MS Learn: API Management
• APIM policy reference
• APIM tiers comparison
• APIM vs Front Door vs App Gateway