Policies

Part C gave the gateway an API model and a route to the backend. A policy is a rule APIM applies while handling a call. Policy statements use XML: one can check a token, another can limit calls, and another can remove a response header. You choose both the rule and where it runs. A gateway also has built-in behavior, such as routing, so a policy is not the only thing it does.

Policy

A rule in APIM's XML policy language. It can apply at the service-wide, workspace, product, API, or operation scope, depending on the gateway and feature. A narrower policy section uses <base /> to include policies inherited from broader scopes. Check every section when you add a narrow rule: omitting <base /> can prevent an intended broader rule from running there.

Scope means how widely the rule applies. A product-scope policy can apply to APIs in that product; an operation-scope policy can target one method and path. The scope is not the identity of the rate-limit counter: rate-limit-by-key counts by its configured key. Two callers sharing that key share the counter.

<inbound>
  <base />
  <rate-limit-by-key calls="10" renewal-period="60"
      counter-key="@(context.Subscription.Id)" />
</inbound>

Policies run in a pipeline, an ordered path through a request. Inbound runs before forwarding; use it to validate a token, check a rate limit, or change the request. Backend controls forwarding to the service. Outbound runs on the response; use it to remove a response header or store a cacheable answer. On-error runs when APIM encounters an error during processing. Each policy also has its own allowed sections: moving a policy to a different section is not always valid.

Start with a few common policies. Rate-limit-by-key caps calls over a short window using a key you choose; quota-by-key counts a longer allowance and is unavailable in v2 tiers.¹ A subscription ID is one possible key when subscriptions are required. Validate-jwt can check a signed token, including its intended audience when configured. Cache-lookup checks inbound for an existing answer; cache-store stores a GET response outbound. CORS tells browsers which web origins may read a response. Some browser requests first send a preflight OPTIONS check. CORS does not authenticate a caller or block non-browser clients.

Here is an illustrative inbound section for the protected partner API. Replace the example tenant and audience with your own values, test token claims, and confirm the subscription requirement before using the subscription ID as a counter key:

<!-- inbound: applies before the backend is touched -->
<inbound>
  <base />
  <cors>
    <allowed-origins><origin>https://shop.campux.co</origin></allowed-origins>
    <allowed-methods><method>GET</method></allowed-methods>
    <allowed-headers><header>authorization</header></allowed-headers>
  </cors>
  <validate-jwt header-name="Authorization" require-scheme="Bearer"
    failed-validation-httpcode="401">
    <openid-config url="https://login.microsoftonline.com/11111111-1111-1111-1111-111111111111/v2.0/.well-known/openid-configuration" />
    <audiences><audience>api://22222222-2222-2222-2222-222222222222</audience></audiences>
  </validate-jwt>
  <rate-limit-by-key calls="100" renewal-period="60"
    counter-key="@(context.Subscription.Id)" />
</inbound>

Read the section top to bottom: inherit broader rules, handle allowed browser origins, validate a Bearer token for this API's audience, then limit calls by subscription. APIM returns 429 when the rate limit is exceeded, but distributed counters are approximate; do not promise exactly the 101st call is rejected. The example is a section inside a larger <policies> document, not a complete deployable file.

First, policies are code. A rate limit is production behaviour; a JWT check is a security control. So the XML lives in the repository, is deployed by the Class Twenty-Two pipeline, and is reviewed like everything else — because portal-edited policy is the Class Twenty click-drift problem reborn, a production change with no diff, no review, and no way to reproduce. The moment someone "just tweaks a policy in the portal," you have an environment whose behaviour no file describes.

Second, policies stay traffic-shaped. Authentication, limiting, caching, transformation, header hygiene — the gateway's proper work is about how requests flow. The moment business logic creeps into policy XML — a discount calculation, a pricing rule, an entitlement decision — you have hidden part of the application in a place no debugger visits, outside the test suite, outside the code review path most teams wire for application code. Six months later a pricing bug hunt ends somewhere nobody thought to look. The boundary is the track's spine, stated once more: the gateway decides whether and how a request travels; the backend decides what it means.

Business logic in policy is a bug hunt in a place no debugger visits.

The example rate limit counts on context.Subscription.Id. That assumes the partner API requires subscriptions and each partner uses its own key. Part E explains subscriptions; Part F covers token validation and backend access; Part G covers network placement. A rate limit alone is not an identity or security design.

This part carries no lab. There is no cloud resource to stand up for policy itself — the gateway already exists from 38b and the API from 38c, so writing and reasoning about policy XML is the whole exercise, and the game above is where you do it with your hands.