Azure API Management and policy-based gateways

Overview

Azure API Management, or APIM, is a managed platform for publishing, securing, governing, observing, and productizing APIs. It places a gateway between API consumers and backend services while providing a management plane and developer-facing discovery capabilities.

The gateway is the runtime data plane. It:

• Accepts client requests.
• Matches them to APIs and operations.
• Executes configured policies.
• Routes requests to backend services.
• Processes backend responses.
• Emits telemetry.

APIM can provide a stable public contract while backend implementations evolve. It can expose legacy services through modern URLs, validate tokens, enforce traffic policies, authenticate to private backends, transform payloads, cache responses, and route requests across backend pools.

APIM is not automatically the correct choice for every API. It introduces cost, latency, configuration ownership, deployment dependencies, and another production component. It is most valuable when multiple APIs or consumer groups need consistent governance, security, onboarding, analytics, or hybrid gateway placement.

For interviews, candidates should be able to explain:

• The gateway, management plane, developer portal, APIs, products, subscriptions, and workspaces.
• The difference between managed, workspace, and self-hosted gateways.
• How the policy execution pipeline works.
• How policy scopes and <base /> inheritance interact.
• Where authentication, routing, transformation, throttling, caching, retries, and error handling belong.
• Why APIM does not replace backend business authorization, a web application firewall, or sound API design.
• How tiers, networking, scaling, multi-region design, and self-hosted operations affect architecture.
• How to manage policies as code and test gateway behavior safely.

Core Concepts

Main API Management Components

An API Management service contains three major capabilities:

• Gateway: Runtime component that proxies requests, applies policies, and collects telemetry.
• Management plane: Configuration surface used to provision the service, import APIs, define products, configure policies, and manage deployments.
• Developer portal: Consumer-facing site for API discovery, documentation, onboarding, subscriptions, testing, and usage visibility.

The gateway is on the request path. The management plane and developer portal are not required for every individual API call.

This separation matters operationally. A management-plane outage or temporary self-hosted gateway disconnection does not always imply that an already-running gateway immediately stops processing its current configuration.

APIs and Operations

An APIM API represents a consumer-facing API contract and maps its operations to a backend implementation.

APIs can be imported or defined from formats and services such as:

• OpenAPI.
• WSDL and SOAP.
• OData.
• GraphQL.
• gRPC in supported gateway configurations.
• App Service, Functions, Logic Apps, and Container Apps.

An operation defines:

• HTTP method.
• Public URL template.
• Path and query parameters.
• Request and response representations.
• Operation-level policies.

APIM can present a public route that differs from the backend route. This abstraction allows backend relocation and structural changes, but excessive rewriting can make the gateway a hidden application layer.

Products and Subscriptions

A product packages one or more APIs for a consumer audience. A published product can be:

• Open.
• Protected by an APIM subscription.
• Subject to product-specific policy, quota, or rate limits.
• Visible to selected developer groups.

An APIM subscription provides a key associated with a scope such as a product, API, or broader service access. Subscription keys are useful for:

• Consumer identification.
• Usage analytics.
• Per-subscription throttling and quotas.
• Developer onboarding.
• Key rotation.

A subscription key is not a substitute for user or workload authentication when the API needs a trustworthy caller identity. Keys can be copied and shared. Use OAuth access tokens, client certificates, or another strong identity mechanism as appropriate.

Developer Portal

The developer portal supports:

• API documentation.
• Interactive API calls.
• Consumer signup and onboarding.
• Product discovery.
• Subscription-key management.
• API definition downloads.
• Usage visibility.

It is useful for partner and internal API programs, but it should not be confused with the runtime gateway.

Portal governance should include:

• Which APIs and products are discoverable.
• Which users can subscribe.
• Whether subscription approval is automatic.
• How sample requests handle credentials.
• How documentation versions align with deployed behavior.

Gateway as a Facade

The gateway provides a stable consumer-facing boundary:

Client
  -> api.contoso.example/orders
  -> API Management gateway
  -> private internal backend

The facade can hide:

• Backend hostnames.
• Internal path structures.
• Implementation technology.
• Authentication mechanism used between APIM and the backend.
• Regional or versioned backend selection.

The facade should preserve a coherent API contract. It should not hide incompatible business semantics or make operationally significant behavior impossible for teams to discover.

Managed Gateway

Every APIM service tier includes a built-in managed gateway. Azure operates the gateway infrastructure, while the customer configures APIs, policies, networking, capacity, and monitoring.

Managed gateway advantages include:

• Lower operational burden.
• Integrated scaling and service management.
• Azure networking and monitoring integration.
• Centralized policy deployment.
• Supported multi-region or zone features in appropriate tiers.

Trade-offs include:

• Tier-dependent features and cost.
• Traffic may travel through Azure gateway locations even when backends are elsewhere.
• Platform limits and scaling characteristics.
• Network integration complexity for private backends.

Workspace Gateways

Workspaces support federated API management. API teams can manage their own APIs, products, subscriptions, and related configuration while a central platform team retains governance of the APIM service.

A workspace can use the service's default managed gateway in supported v2 tiers or one or more dedicated workspace gateways in supported Premium configurations.

Workspace gateways provide runtime isolation between workspace workloads, but they do not support every feature of the default gateway. Architecture decisions must use the current tier and gateway feature matrix rather than assuming all APIM gateways behave identically.

Self-Hosted Gateway

The self-hosted gateway is a containerized APIM gateway deployed near backends in an on-premises, edge, or other-cloud environment.

Benefits include:

• Lower latency to local backends.
• Reduced cross-environment data transfer.
• Local traffic routing for compliance.
• Central policy and API management from Azure.
• Hybrid and multicloud API governance.

The customer operates:

• Container or Kubernetes infrastructure.
• Scaling and availability.
• Image upgrades.
• Resource limits.
• Local networking and TLS.
• Persistent configuration backup.
• Local logging and monitoring.

The gateway still needs outbound connectivity to its APIM configuration endpoint for updates, status, and optional telemetry. During a temporary disconnection, a running gateway can continue using cached configuration. With configuration backup, a stopped gateway can restart from persisted configuration.

Production deployments should pin an intentional gateway image version instead of relying on a rolling tag that can introduce unplanned upgrades.

APIM Service Tiers

APIM tiers differ in:

• Provisioning and scaling model.
• Capacity and service limits.
• Virtual network capabilities.
• Private endpoints.
• Availability zones.
• Multi-region deployment.
• Self-hosted gateway availability.
• Workspaces and workspace gateways.
• Caching and protocol features.
• SLA and cost.

Broad tier families include:

• Classic dedicated tiers.
• V2 tiers with faster provisioning and newer networking options.
• Consumption for variable serverless traffic.

Do not choose a tier only by average request volume. Evaluate:

• Peak concurrency and policy cost.
• Private backend connectivity.
• Required availability model.
• Multi-region needs.
• Protocol support.
• Expected scale-out time.
• Developer portal and analytics requirements.
• Gateway type and policy compatibility.

Load test with representative payloads and policies. Gateway throughput depends on backend latency, connection concurrency, body sizes, policy expressions, transformations, logging, and cache behavior.

The Policy Pipeline

APIM policies are XML statements executed sequentially in four sections:

<policies>
  <inbound>
    <base />
  </inbound>
  <backend>
    <base />
  </backend>
  <outbound>
    <base />
  </outbound>
  <on-error>
    <base />
  </on-error>
</policies>

The sections are:

• Inbound: Runs as the request enters the gateway. Common tasks include token validation, throttling, header normalization, request transformation, and backend selection.
• Backend: Controls forwarding behavior, retries, timeouts, and backend routing.
• Outbound: Runs after a backend response. Common tasks include response transformation, header removal, caching, and response normalization.
• On-error: Runs when policy execution enters an error state. It can log context or return a controlled error.

If an error occurs during normal processing, remaining statements are skipped and execution moves to on-error.

API Management policies are not Azure Policy definitions. APIM policies change runtime request behavior; Azure Policy evaluates governance compliance of Azure resources.

Policy Scopes

Policies can be configured at scopes from broadest to narrowest:

• Global.
• Workspace.
• Product.
• API.
• Operation.

Use broad scopes for universal controls:

• Correlation IDs.
• Baseline security headers.
• Required token validation.
• Common diagnostics.

Use narrow scopes for:

• Operation-specific authorization.
• Backend routing.
• Specialized transformations.
• Different quotas or timeouts.

Policies at multiple scopes are combined through inheritance. The location of <base /> determines when parent policies execute.

Policy Inheritance and Base

Include <base /> in each section when child policies should inherit parent behavior:

<inbound>
  <base />
  <rewrite-uri template="/internal/orders/{orderId}" />
</inbound>

Removing <base /> can omit policies from broader scopes. This can unintentionally bypass global authentication, throttling, telemetry, or header controls.

The position matters:

<inbound>
  <validate-header name="X-Required-Client" />
  <base />
</inbound>

Here, the child validation executes before inherited parent policies.

Use Azure Policy, CI validation, or another governance control to require appropriate inheritance. Review the effective policy, not only the local XML fragment.

Policy Expressions

Policy expressions embed an allowed subset of C# expressions:

<set-header name="x-correlation-id" exists-action="skip">
  <value>@(context.RequestId.ToString())</value>
</set-header>

Expressions can inspect:

• Request and response data.
• Matched parameters.
• Subscription and user context.
• Deployment region.
• Variables.
• Validated token claims.

Use expressions for small edge decisions, not substantial business logic. Complex expressions:

• Are harder to test and review.
• Increase gateway CPU cost.
• Can consume request bodies.
• Can create runtime failures.
• Hide behavior from backend owners.

If logic requires databases, complex workflows, domain state, or frequent independent releases, it belongs in an application or dedicated service.

Named Values and Secrets

Named values centralize policy configuration such as:

• Backend identifiers.
• Audience values.
• Feature switches.
• Nonsecret constants.
• Secret references.

Secret named values can reference Azure Key Vault. Use APIM managed identity and narrow Key Vault permissions.

Do not embed credentials directly in policy XML. Also remember that people who can edit policies may be able to use APIM's managed identity to acquire or forward tokens. Policy-edit permissions are privileged and must be governed.

Backend Entities

A backend entity defines a reusable backend configuration. Policies can route by backend ID:

<set-backend-service backend-id="orders-primary" />

Backends can support:

• Centralized endpoint configuration.
• Managed identity or certificate authentication.
• Load-balanced pools.
• Circuit-breaker rules in supported gateways.
• Runtime routing decisions.

Backend entities reduce repeated URLs and make routing intent clearer. Restrict dynamic routing so tokens or secrets cannot be forwarded to an attacker-controlled destination.

Routing and Version Abstraction

APIM can route based on:

• API version.
• Header or query parameter.
• Geography.
• Product or subscription.
• Canary percentage.
• Backend health or pool configuration.

Use versions for breaking contract changes. Use revisions for nonbreaking changes and controlled publication of the same version.

A gateway can support gradual migration:

Public v1 -> legacy backend
Public v2 -> new backend

Do not use policy routing to pretend that incompatible contracts are one version. The public API definition and documentation must remain truthful.

Networking

Common designs include:

• Public APIM gateway to public backends.
• Public gateway to private backends through virtual network integration.
• Private gateway reachable only through private networking.
• APIM behind Azure Front Door or Application Gateway for global routing or WAF.
• Self-hosted gateway beside on-premises backends.

Network design must address:

• Inbound client path.
• Outbound backend path.
• DNS.
• TLS certificates and custom domains.
• Private endpoints.
• Network security groups and route tables.
• Identity-provider and telemetry endpoints.
• Management-plane connectivity.

APIM is an API gateway, not a full web application firewall. Use Front Door or Application Gateway WAF when layer-7 web threat filtering is required.

Backend Authentication

APIM can authenticate to backends using:

• Managed identity.
• Client certificates.
• Basic credentials for legacy systems.
• Static headers or keys stored securely.
• OAuth credentials through supported mechanisms.

Managed identity is preferred for supported Azure or Microsoft Entra-protected backends:

<authentication-managed-identity
    resource="api://orders-backend-client-id" />

APIM obtains and caches a token and sets the backend Authorization header.

The frontend caller's identity and APIM's backend identity solve different problems:

• Frontend token identifies and authorizes the consumer.
• APIM managed identity authorizes the gateway to call the backend.

If the backend needs the original user identity, use a deliberate delegation design rather than replacing the user's token without considering authorization semantics.

Observability

APIM can emit:

• Azure Monitor metrics.
• Diagnostic logs.
• Application Insights telemetry.
• Request traces.
• Event Hub events.
• Self-hosted local logs and metrics.

Monitor:

• Gateway latency.
• Backend latency.
• Request volume.
• Status-code distribution.
• Policy failures.
• Authentication failures.
• Throttled and quota-rejected requests.
• Capacity and saturation.
• Backend pool health.
• Cache hit ratio.
• Regional behavior.

Separate gateway time from backend time. Otherwise teams may optimize the wrong component.

Avoid logging:

• Access tokens.
• Subscription keys.
• Authorization headers.
• Sensitive bodies.
• Personal data without an approved purpose.

Caching

APIM can cache suitable GET responses to reduce latency and backend load.

Cache design must define:

• Which responses are cacheable.
• Cache key dimensions.
• Whether authorization affects the response.
• Vary-by headers and query parameters.
• Time to live.
• Invalidation behavior.
• Whether internal or external cache is used.

The built-in cache is volatile. A cache miss or outage can cause a sudden load increase, so rate limiting should still protect the backend.

Do not cache personalized or authorization-dependent responses under a shared key.

Retries, Timeouts, and Circuit Breaking

The gateway can configure:

• Backend timeout.
• Request-body buffering for retry.
• Fixed, linear, or exponential retry.
• Backend switching.
• Backend pool load balancing.
• Circuit breakers in supported gateways.

Retries are safe only when:

• The operation is idempotent.
• The body can be replayed.
• Total latency remains within the client budget.
• Retried failures are transient.
• Retry multiplication across client, gateway, and backend is controlled.

Do not add broad retries to non-idempotent POST requests without an idempotency design.

Error Handling

Use on-error to:

• Map internal gateway failures to a stable external response.
• Add correlation information.
• Emit safe diagnostic events.
• Handle selected policy errors.

Avoid exposing:

• Backend hostnames.
• Stack traces.
• Raw policy exceptions.
• Token-validation details useful to attackers.
• Secret named values.

Return standards-based, consistent errors where practical, but keep enough server-side context for diagnosis.

APIM and Backend Responsibilities

Good edge responsibilities include:

• Transport security.
• Token validation.
• Coarse capability authorization.
• Rate limiting and quotas.
• Routing and protocol adaptation.
• Correlation and telemetry.
• Small structural transformations.

Backend responsibilities include:

• Object-level authorization.
• Business invariants.
• Domain validation.
• Transactions.
• Data consistency.
• Business auditing.
• Protection against bypass if the backend is reachable through another path.

Defense in depth can mean validating tokens at APIM and again in the backend. Edge validation protects the gateway contract; backend validation protects the service boundary.

Infrastructure and Policy as Code

Treat APIM configuration as deployable source:

• API definitions.
• Policy XML.
• Named-value references.
• Products and subscriptions.
• Backends.
• Diagnostics.
• Custom domains.
• Network configuration.

Use:

• Infrastructure as code.
• Pull-request review.
• Environment-specific parameters.
• Policy linting and tests.
• Staged deployment.
• Revisions for controlled changes.
• Drift detection.

Avoid editing production policies only through the portal. A small XML change can alter authentication or routing for every request.

Common Mistakes

• Treating subscription keys as strong user authentication.
• Removing <base /> and bypassing parent protections.
• Putting complex business logic in policy expressions.
• Granting broad policy-edit permissions.
• Forwarding APIM managed identity tokens to dynamic or untrusted backends.
• Assuming every gateway type supports every feature.
• Selecting a tier from average traffic without load testing.
• Exposing a private backend through another route that bypasses APIM.
• Retrying non-idempotent operations.
• Caching personalized responses under a shared key.
• Logging tokens or sensitive payloads.
• Using APIM when one simple internal API has no meaningful gateway requirement.

When APIM Is a Good Fit

APIM is a strong fit when:

• Many APIs need consistent security and governance.
• Partners need onboarding, products, keys, and documentation.
• Backends span Azure, on-premises, and other clouds.
• A stable facade must outlive backend migrations.
• Central traffic controls and analytics are required.
• Multiple teams need federated API ownership.

It may be excessive when:

• There is one low-risk internal API.
• Platform cost and latency exceed the governance benefit.
• The only requirement is basic reverse proxying.
• Existing ingress already provides the required controls.
• The team cannot operate or govern the added policy layer.