9. Glossary and Cheatsheet

The ten-second lookup.

Glossary

Term	One line
API	A named set of operations sharing a URL suffix, a backend, and a policy scope; an ARM child resource of the service
API Center	A separate Azure service that catalogues APIs across gateways — inventory only, no traffic
APIM instance / service	The ARM resource Microsoft.ApiManagement/service; regional, globally unique name, owns everything else here
APIOps	A pattern (with Microsoft-published tooling) that extracts APIM configuration to git-friendly files and publishes them to a target instance ⚠️ verify current tooling status
<base />	The element marking where the parent scope's policy runs inside the current scope; omitting it silently discards the parent's policy for that section
Backend	A first-class entity holding a backend URL, credentials, client certificate, and circuit-breaker rules; reusable across APIs and selectable with set-backend-service
Backend pool	A group of backends with weighted or priority routing — the load-balancing construct, heavily used in AI-gateway designs
Capacity	The published utilisation percentage of a gateway instance; the recommended autoscale signal, and a measure of concurrency rather than CPU
Circuit breaker	A rule on a backend entity that stops sending traffic to a failing backend for a trip duration
Consumption tier	Serverless, per-call, shared-infrastructure tier; no VNet, no developer portal, no built-in cache, cold starts
Developer portal	The generated, customisable site where consumers discover APIs and self-serve subscriptions; managed or self-hosted, and must be explicitly published
Developer tier	Full classic feature set, one unit, no SLA — for building against, never for production
Diagnostic setting	The ARM resource routing GatewayLogs and metrics to Log Analytics, storage, or Event Hubs; not on by default
Direct management API	The legacy <name>.management.azure-api.net endpoint authenticating outside Entra ID; disable it
External cache	An Azure Cache for Redis attached to the instance; shared across units and regions, unlike the internal cache
Gateway	The data-plane component that serves traffic at *.azure-api.net or a custom domain
Internal cache	The small, per-instance, tier-dependent built-in response cache
Logger	An APIM entity pointing telemetry at Application Insights or Event Hubs, with a sampling percentage
Named value	An instance-level key/value referenced from policy as {{name}}; plain, secret, or a Key Vault reference (the correct choice for anything sensitive)
Operation	One method + URL template within an API; the finest policy scope
Policy	The XML document defining <inbound>, <backend>, <outbound>, <on-error> behaviour at a given scope
Policy expression	Inline C# in @(...) or @{ ... } with access to the context object
Policy fragment	A reusable named block of policy XML included with <include-fragment>
Product	A commercial bundle of APIs with terms — subscription required, approval required, quota, portal visibility
Revision	A non-breaking working copy of an API, tested at ;rev=N and promoted by "make current"; APIM's fastest rollback
Scope (policy)	global → workspace → product → API → operation; all applicable scopes run, nested
Self-hosted gateway	A containerised copy of the data plane run in your own cluster or datacentre, configured from Azure; Premium/Developer
Soft delete	A deleted instance is retained and keeps its globally unique name reserved until purged or expired ⚠️ verify current window
Subscription (APIM)	The entitlement joining a consumer to a product/API/all-APIs, carrying primary and secondary keys — not an Azure subscription
Subscription key	The bearer secret in Ocp-Apim-Subscription-Key; identifies and meters a consumer, does not authenticate them
Unit	A fixed, tier-specific slice of gateway capacity; you scale by count, not by size
Version / version set	A consumer-visible variant of an API for breaking changes, distinguished by path, query or header
VNet integration — external	Injected into a subnet, retains a public gateway IP
VNet integration — internal	Injected into a subnet with no public endpoint; the enterprise default, usually behind an Application Gateway
v2 tiers	Basic v2 / Standard v2 / Premium v2 — a newer platform with much faster provisioning and a different feature and networking matrix ⚠️ verify current GA status
Workspace	A Premium construct partitioning one instance so teams own their APIs with their own RBAC ⚠️ verify current availability and limits

Renamed or easily confused elsewhere in Azure: Azure AD → Microsoft Entra ID (the issuer validate-jwt points at); Azure AD B2C → Microsoft Entra External ID (partner and consumer sign-in); Azure Cognitive Services → Azure AI Services (the AI-gateway backends).

Cheatsheet — the commands you'll actually type

# --- instance lifecycle -------------------------------------------------------
az apim create -g $RG -n $APIM -l $LOC --sku-name Developer \
   --publisher-name "Contoso" --publisher-email "apis@contoso.com" --no-wait
az apim show -g $RG -n $APIM --query "{state:provisioningState, sku:sku.name, ips:publicIpAddresses}"
az apim update -g $RG -n $APIM --sku-name Standard --sku-capacity 2   # scale (slow)

# --- the soft-delete trap: why your re-create fails --------------------------
az apim deletedservice list -o table
az apim deletedservice purge --service-name $APIM --location $LOC

# --- APIs and operations ------------------------------------------------------
az apim api list -g $RG -n $APIM -o table
az apim api import -g $RG -n $APIM --api-id orders --path orders \
   --specification-format OpenApi --specification-path ./orders.yaml
az apim api show -g $RG -n $APIM --api-id orders
az apim api delete -g $RG -n $APIM --api-id orders --delete-revisions

# --- products and subscriptions ----------------------------------------------
az apim product list -g $RG -n $APIM -o table
az apim product api add -g $RG -n $APIM --product-id partner --api-id orders
az apim subscription list -g $RG -n $APIM -o table
az apim subscription keys regenerate -g $RG -n $APIM --sid <sub-id> --key-kind secondary

# --- named values (prefer Key Vault references over literals) ----------------
az apim nv list -g $RG -n $APIM -o table
az apim nv show -g $RG -n $APIM --named-value-id tenant-id

# --- backup / restore ---------------------------------------------------------
az apim backup -g $RG -n $APIM --backup-name "$APIM-$(date +%F)" \
   --storage-account-name $SA --storage-account-container apim-backups
az apim restore -g $RG -n $APIM --backup-name <name> \
   --storage-account-name $SA --storage-account-container apim-backups

# --- observability ------------------------------------------------------------
az monitor diagnostic-settings categories list --resource $(az apim show -g $RG -n $APIM --query id -o tsv)
az monitor metrics list --resource $(az apim show -g $RG -n $APIM --query id -o tsv) \
   --metric Capacity --interval PT5M

# --- calling through the gateway ---------------------------------------------
curl -i "https://$APIM.azure-api.net/orders/v1/orders/42" \
     -H "Ocp-Apim-Subscription-Key: $KEY" \
     -H "Authorization: Bearer $TOKEN"

# --- teardown -----------------------------------------------------------------
az group delete -n $RG --yes --no-wait      # then remember to purge (above)

⚠️ Verify command names and flags against your az version — the apim command group has grown and some subcommands have been renamed.

Policy snippets worth memorising

<!-- The skeleton. Every policy document has exactly these four sections. -->
<policies>
  <inbound><base /></inbound>
  <backend><base /></backend>
  <outbound><base /></outbound>
  <on-error><base /></on-error>
</policies>

<!-- Token validation with a claim check — the actual security control. -->
<validate-jwt header-name="Authorization" failed-validation-httpcode="401">
  <openid-config url="https://login.microsoftonline.com/{{tenant-id}}/v2.0/.well-known/openid-configuration" />
  <audiences><audience>{{api-audience}}</audience></audiences>
  <required-claims>
    <claim name="roles" match="any"><value>Orders.Read</value></claim>
  </required-claims>
</validate-jwt>

<!-- Rate limit by a dimension you choose; quota for commercial entitlement. -->
<rate-limit-by-key calls="600" renewal-period="60"
                   counter-key="@(context.Subscription?.Id ?? context.Request.IpAddress)" />
<quota-by-key calls="1000000" renewal-period="2592000"
              counter-key="@(context.Subscription.Id)" />

<!-- Response caching. Get vary-by wrong and you serve one tenant another's data. -->
<cache-lookup vary-by-developer="true" vary-by-developer-groups="false" downstream-caching-type="none">
  <vary-by-header>Accept</vary-by-header>
</cache-lookup>
<!-- ...and in outbound: -->
<cache-store duration="60" />

<!-- Keyless backend auth. -->
<authentication-managed-identity resource="api://orders-backend"
                                 client-id="{{apim-uami-client-id}}" />

Resource ID shapes

# The service
/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.ApiManagement/service/{name}

# An API inside it
/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.ApiManagement/service/{name}/apis/{apiId}

# An operation
/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.ApiManagement/service/{name}/apis/{apiId}/operations/{operationId}

# A product, a named value, a backend
.../Microsoft.ApiManagement/service/{name}/products/{productId}
.../Microsoft.ApiManagement/service/{name}/namedValues/{namedValueId}
.../Microsoft.ApiManagement/service/{name}/backends/{backendId}

These are what every role assignment scope, Azure Policy assignment, and error message is written against. Note that the child resources have real IDs — that's the "configuration is infrastructure" property in one line.

Endpoints

https://<name>.azure-api.net                      # gateway (data plane)
https://<name>.developer.azure-api.net            # developer portal
https://<name>.management.azure-api.net           # legacy direct management API — disable it
https://management.azure.com/...                  # ARM (control plane)

Limits worth knowing — with the scope each is counted at

A number without a scope is useless in Azure. Every value below varies by region, tier, and subscription type — ⚠️ verify all of them against current Azure docs before designing around them.

Limit	Counted at
APIM instances	per subscription per region
Units	per instance per region, capped by tier
Additional regions	per instance (Premium only)
Self-hosted gateways	per instance
APIs, products, subscriptions, named values, certificates, backends, policy fragments	per service instance
Request/response body size for validation, transformation and caching policies	per request
Backend request timeout (default and maximum)	per request
Internal cache size	per instance, tier-dependent
Soft-delete retention for a deleted instance	per deleted instance
ARM control-plane request rate	per subscription

The five things people get wrong

1. A subscription key is not authentication. It meters a consumer. validate-jwt authenticates.
2. Omitting <base /> silently disables the parent scope's policy — including your global token validation. Lint for it in CI.
3. Capacity is concurrency, not CPU. A slow backend saturates the gateway at unchanged traffic; the fix is a timeout and a circuit breaker, not more units.
4. terraform destroy leaves a soft-deleted instance holding your globally unique name. Purge it — or, if the delete was an accident, restore it instead of rebuilding.
5. Reader does not mean call, and Contributor does not mean call either. Control-plane RBAC governs configuration; the gateway's data plane is governed by keys, tokens and certificates.

---

← Back to the Azure API Management overview · ← Previous: Interview Questions