2. Core Concepts

Every noun you will meet in the portal, defined. The format is term → plain-English analogy → precise technical definition, because a term you can only recite is a term you'll misuse.

APIM has more vocabulary than most Azure services, and — unusually — most of it describes child resources of one ARM resource rather than separate services. Read Architecture next for how these pieces behave at runtime.

The top-level resource

Term	Analogy	Technical definition
API Management service (the "instance")	The reception desk itself — one building, one desk, many offices behind it	A regional ARM resource of type Microsoft.ApiManagement/service with a globally unique name, a tier (SKU), a unit count, one or more gateway hostnames, and a system-assigned or user-assigned managed identity. It owns every other entity on this page
Unit	A till at the desk — add tills to serve more queue	A fixed, tier-specific slice of gateway capacity (CPU, memory, and therefore throughput). You scale by changing the unit count; you do not choose the VM size. Throughput per unit varies by tier and by what your policies do ⚠️ verify current per-unit throughput guidance
Gateway hostname	The building's street address	By default <name>.azure-api.net; you may attach custom domains (with certificates, usually from Key Vault) for the gateway, the developer portal, and the management endpoint separately
Region / additional location	A second reception desk in another city, same company	Classic Premium can add regional deployments; traffic is routed to the nearest by Azure Traffic Manager behind the single hostname, and each region has its own unit count. Not available below Premium

Scoped to a resource group inside a subscription like any other resource — see the scope hierarchy.

The API surface

Term	Analogy	Technical definition
API	One office behind the desk, with its own door sign	A named collection of operations sharing a URL suffix (the path segment after the gateway hostname), a backend service URL, a set of subscription/auth requirements, and a policy scope. Type Microsoft.ApiManagement/service/apis. Imported from OpenAPI, WSDL, WADL, an App Service, a Function App, a Logic App, or created by hand
Operation	One service offered at that office	A single method + URL template pair (GET /orders/{id}) with its own parameters, request/response schemas, and — importantly — its own policy scope. The finest grain at which you can attach behaviour
API type	—	HTTP/REST is the default; APIM also fronts SOAP (pass-through, or SOAP-to-REST where it generates a REST facade), WebSocket, GraphQL (pass-through or synthetic, resolver-backed), and gRPC ⚠️ verify current per-tier support for GraphQL, gRPC and WebSocket
Backend	The office's internal phone extension	Either a plain URL on the API, or a first-class Microsoft.ApiManagement/service/backends entity holding a URL, credentials, a client certificate, a circuit breaker rule, and — for load balancing — membership in a backend pool. Reusable across APIs; use the entity, not the URL, for anything real
API version	A new edition of the product, sold alongside the old one	A deliberate, consumer-visible variant for breaking changes, distinguished by path segment (/v2/), query string, or header. Versions of an API are grouped in a version set. Consumers choose when to move
Revision	A draft of the current edition, promoted when ready	A non-breaking, invisible-to-consumers working copy of an API. You edit revision 2 while revision 1 stays current, test it at its own revision URL (;rev=2), then make it current — which is an atomic switch, and the reason revisions are the fastest rollback APIM offers. A change log entry can accompany the switch

The exam question, and the real-world one: versions are for changes that break consumers and must coexist; revisions are for changes that don't break anyone and replace the live behaviour when you say so. Using a version where a revision belongs leaves you maintaining two contracts forever. Using a revision where a version belongs breaks somebody's client at 4 p.m. on a Friday.

The governance surface

Term	Analogy	Technical definition
Product	A ticket type — "day pass", "annual membership"	A named bundle of one or more APIs with its own terms: published or not, requiring a subscription or not, requiring approval or not, an optional subscriber limit, its own policy scope (where quotas usually live), and its own developer-portal page. The unit of packaging and entitlement
Subscription	The ticket a specific person holds	An entitlement record granting a user (or an application) access to a product — or, with the right settings, to a single API or to all APIs. It carries two keys (primary and secondary, so you can rotate without downtime) and a state (active, suspended, expired, submitted, rejected, cancelled)
Subscription key	The number printed on the ticket	A bearer secret sent in the Ocp-Apim-Subscription-Key header or the subscription-key query parameter. It identifies and meters a consumer; it does not authenticate a user. Treat it as a client ID with a quota, not as a credential
User / group	The person's membership record	Developer-portal identities, from the built-in store, Entra ID, or an external OIDC provider. Groups (Administrators, Developers, Guests, plus custom or Entra-backed ones) control which products are visible in the portal
Developer portal	The printed brochure and self-service kiosk	A generated, customisable site where consumers browse published products, read the OpenAPI-derived reference, try calls in the browser, and self-serve a subscription. Managed (hosted by APIM, edited in a visual editor, must be explicitly published) or self-hosted (the open-source portal code, hosted by you). Not available in Consumption tier
Workspace	A branch office with its own manager	A Premium construct that partitions one APIM instance so that a team can own its own APIs, products, and policies with its own RBAC, without seeing or breaking anyone else's — the answer to "we want federated API management without ten instances" ⚠️ verify current workspace availability, limits and gateway model

The pattern to internalise: an API is technical, a product is commercial, a subscription is the join between a product and a consumer. Quotas belong on products (because they're commercial terms); rate limits often belong on APIs or operations (because they protect a backend).

The policy engine

Term	Analogy	Technical definition
Policy	The desk's standing instructions, in order	An XML document defining what happens to a request and response, composed of four sections: <inbound> (before the backend), <backend> (how the call is made), <outbound> (before the response leaves), <on-error> (when anything above throws). Statements execute in document order
Scope	Which desk the instruction is pinned to	Policies attach at global (all APIs) → workspace → product → API → operation. All applicable scopes run, nested from broadest to narrowest
<base />	"…and do whatever the standing instruction above says, here"	The element that marks where the parent scope's policy runs inside the current scope's section. Omit it and you silently discard the parent's policy for that section — the single most common APIM configuration bug
Policy expression	A formula in a cell	An inline C# expression in @(...) (single statement) or @{ ... return x; } (block) with access to a context object — context.Request, context.User, context.Subscription, context.Variables, context.Api, context.Deployment — used to make policies dynamic
Named value	A labelled envelope in the desk drawer	An instance-level key/value entity (Microsoft.ApiManagement/service/namedValues) referenced from policy as {{my-name}}. Three kinds: plain, secret (masked, stored encrypted), and Key Vault reference (APIM fetches it using its managed identity and refreshes periodically ⚠️ verify the current refresh interval). Key Vault references are the correct choice for anything sensitive
Fragment	A boilerplate paragraph you paste into letters	A reusable named block of policy XML included with <include-fragment fragment-id="..." />. The DRY mechanism for a policy you'd otherwise copy into thirty APIs

The policies you will actually use, grouped by why:

• Authorisation: validate-jwt (verify an OIDC/Entra token's signature, issuer, audience and claims), validate-client-certificate, check-header, ip-filter.
• Traffic control: rate-limit and rate-limit-by-key (short-window burst protection, returns 429), quota and quota-by-key (long-window volume entitlement), retry, and the backend circuit breaker (configured on the backend entity, not as a policy).
• Transformation: set-header, set-body, set-query-parameter, rewrite-uri, xml-to-json, json-to-xml, find-and-replace, set-backend-service.
• Caching: cache-lookup / cache-store (response caching) and cache-lookup-value / cache-store-value (arbitrary values — the way you cache a token you fetched in policy).
• Validation: validate-content (body against the OpenAPI schema), validate-headers, validate-status-code, validate-parameters — the "shift left" set that stops malformed traffic before it reaches a backend ⚠️ verify current payload-size limits on schema validation.
• Control flow and outbound calls: choose / when / otherwise, set-variable, send-request (call another service mid-pipeline), return-response (short-circuit and answer without touching the backend), forward-request, emit-metric, trace.
• AI gateway: azure-openai-token-limit / llm-token-limit, azure-openai-emit-token-metric / llm-emit-token-metric, and semantic caching ⚠️ verify current policy names and availability, this set is evolving quickly.

Two things about rate limiting that catch people. First, rate-limit is per-subscription by design and rate-limit-by-key lets you choose the dimension (IP, a JWT claim, a header) — pick deliberately. Second, counters are maintained per gateway node and are not perfectly shared across units or regions, so a limit of 100/minute on a 3-unit multi-region instance is an approximation, not a contract ⚠️ verify current counter-synchronisation behaviour per tier. If the limit must be exact, enforce it in a backend with a shared store.

Caching

Term	Analogy	Technical definition
Internal cache	A pigeonhole behind the desk	A built-in, per-instance response cache with a small tier-dependent size, and no durability guarantees. Not available in Consumption ⚠️ verify current sizes
External cache	A proper stockroom shared by all desks	An Azure Cache for Redis (or any Redis-compatible endpoint) attached to the instance. Larger, shared across units and regions, survives instance scaling, and the only sane option for multi-region or high-volume caching. It is your resource, with your bill and your maintenance

Identity and access

Two separate models, and conflating them is the classic APIM mistake — see the control-plane vs. data-plane discussion in Architecture.

• Azure RBAC governs the ARM resource and its child entities: who may create an API, edit a policy, or change the tier. Built-in roles include API Management Service Contributor (manage the service and its configuration), API Management Service Reader Role, and API Management Service Operator Role (manage the service but not the APIs), plus roles for the developer portal content ⚠️ verify the current built-in role list, it has grown.
• Caller credentials govern the gateway data plane: subscription key, JWT, client certificate. No Azure RBAC role grants the right to call an API through the gateway, and no subscription key grants any ARM permission.
• Managed identity is how the instance itself authenticates outward — to Key Vault for certificates and named values, to Azure OpenAI or Storage as a backend, to Event Hubs for logging. System-assigned (lifecycle tied to the instance) or user-assigned (survives re-creation, which matters given how long APIM takes to provision).

The SKU axis — the most consequential table on this page

Azure services are defined by their tier, and APIM more than most: the tier decides which features exist, not just how fast they run.

Tier	Shape	What it unlocks	What it costs you
Consumption	Serverless, shared, per-call billing	Near-zero idle cost, instant provisioning, automatic scaling	No VNet, no developer portal, no built-in cache, no multi-region, no self-hosted gateway, stricter limits, cold start after idle ⚠️ verify the current exclusion list
Developer	One unit, full feature set, non-production licence	Every classic feature — VNet, portal, self-hosted gateway — at the lowest price	No SLA. Restarts happen. Never production
Basic (classic)	Small production tier	SLA, multiple units, developer portal	No VNet integration, no multi-region ⚠️ verify
Standard (classic)	Mid production tier	More units, higher throughput	No VNet integration (classic), no multi-region ⚠️ verify
Premium (classic)	The enterprise tier	Multi-region, VNet injection in internal or external mode, self-hosted gateways, workspaces, zone redundancy, highest unit ceiling, CA certificates	Substantially the most expensive, per region, always on
Basic v2 / Standard v2 / Premium v2	Newer platform	Fast provisioning (minutes, not tens of minutes), simplified VNet integration, lower entry price for network-integrated scenarios	A feature matrix that differs from classic in both directions — some classic features are absent, some behaviours differ ⚠️ verify the current v2 matrix and GA status before designing against it

How to choose, honestly. Ask three questions in this order: (1) does it need to be on a private network? — that eliminates Consumption and pushes you to Premium or a v2 tier. (2) does it need multi-region active-active? — that is classic Premium. (3) is it production? — that eliminates Developer. Whatever survives, take the cheapest, and remember that tier changes are online but slow on classic tiers, and that scaling down is not always symmetric with scaling up ⚠️ verify current tier-change constraints.

Terms that mean something specific here

• Capacity — a published percentage metric representing how loaded the gateway is. It is the autoscale signal and the health signal, and it is not CPU. See Production.
• Self-hosted gateway — a containerised copy of APIM's data plane that you run in your own Kubernetes cluster, datacentre, or another cloud, configured from and reporting to the Azure control plane. Premium (and Developer) only; billed per gateway ⚠️ verify current billing and v2 support.
• Direct management API — the legacy <name>.management.azure-api.net endpoint with its own access token, separate from ARM. Disable it unless something specifically requires it.
• Backup / restore — APIM's own az apim backup / restore to a storage account, which captures configuration (not the developer portal's every asset in all cases ⚠️ verify current coverage). Distinct from, and not a substitute for, keeping configuration in git.
• Soft delete — a deleted APIM instance is retained for a period, keeping its globally unique name reserved, until it's purged or the retention expires ⚠️ verify the current retention window. This is why a destroy-then-recreate pipeline fails with a name conflict.

---

Next: Architecture →

← Back to the Azure API Management overview · ← Previous: What & Why