Recommend a Solution for API Integration — Lesson

A SaaS provider opens its first partner programme. Within six weeks, 14 partners are calling the same internal HTTP endpoints that the product UI uses. Some partners forget to send headers; some hammer the endpoints during their batch windows; one prototype script accidentally leaks an API key into a public GitHub repo. The architect's response is one decision: put Azure API Management in front, define a partner subscription model with throttling and JWT validation, and rotate every leaked key in minutes. Three months later the partner programme has 80 tenants and the team has not had a single key-leak incident or partner-DOS event. This lesson is about reaching for the right API integration layer — Azure API Management, Application Gateway, Azure Front Door — so that exposing APIs to other systems does not become a permanent operational tax.

We will work through Azure's API integration story the way the AZ-305 exam expects you to: choosing among Azure API Management tiers (Developer, Basic, Standard, Standard v2, Premium, Premium v2, Consumption), comparing APIM to Application Gateway and Front Door as API frontends, and configuring policies, versioning, and self-hosted gateways for hybrid deployments. Reference: the AZ-305 exam study guide, particularly Chapter 4 Skill 4.2 on API integration.

Why This Matters

APIs are the contract surface between teams and between organisations. The right integration layer in front of them gives you authentication, rate limiting, transformation, versioning, observability, and developer-portal documentation — all without any one backend team having to build it. Without an API gateway, every backend reinvents these concerns badly. The AZ-305 exam tests this LO because picking the wrong integration product (or the wrong APIM tier) makes a project either cripplingly expensive or fundamentally unable to meet integration requirements.

The career payoff is concrete: every partner-integration project, every public API launch, every internal mesh that needs a "front door for APIs" touches this LO. If you can match a workload — public B2C API, B2B partner gateway, internal microservice mesh, hybrid on-prem-bridged API — to the right Azure service and tier, configure policies (validate-jwt, rate-limit-by-key, transform, retry), and integrate with VNet / Private Link cleanly, you will pass this slice of the exam and design API integration like a senior architect.

Prerequisites

Before working through this lesson, make sure you can answer each prompt below in one or two sentences.

• API gateway concept. Can you describe what an API gateway does? — Self-check: name three concerns it addresses.
• OpenAPI / Swagger. Are you familiar with the spec? — Self-check: what is the relationship between an OpenAPI document and an API in APIM?
• JWT and OAuth $2.0. Do you understand how Entra ID issues tokens that APIs validate? — Self-check: which claim identifies the calling application?
• L4 vs L7 load balancing. Do you know the difference and which is appropriate for HTTPS routing? — Self-check: where do Application Gateway and Front Door sit?
• Throttling concepts. Can you describe per-key rate limiting and quota? — Self-check: what is the difference between a rate limit and a quota?

If any of these feels shaky, pause and review the API and identity modules in Unit 1 and Unit 4 of the AZ-305 guide.

Learning Objectives

By the end of this lesson, you will be able to:

1. Analyse an API integration workload (audience, traffic shape, security needs, geographic distribution, dev-portal needs) and translate it to an integration service.
2. Evaluate trade-offs between Azure API Management tiers (Developer, Basic, Standard / v2, Premium / v2, Consumption).
3. Recommend between APIM, Application Gateway, Front Door, and combinations for a given API exposure scenario.
4. Design APIM policies (validate-jwt, rate-limit-by-key, set-header, mock-response, retry) for common requirements.
5. Configure APIM in a VNet (internal vs external mode) and Private Link for backend integration.
6. Recognise anti-patterns — Developer tier in production, Consumption tier for VNet-only APIs, missing versioning strategy — and rewrite them.

Building Blocks

Read this section as a glossary. Each term follows the same shape: analogy, formal definition, why it matters.

API gateway — A facade in front of one or more backend APIs that centralises cross-cutting concerns. Like a hotel concierge: every request is greeted, validated, routed, and rate-limited. Formally, a network appliance that terminates client connections, applies policies, and forwards to backends. It matters because backends should not implement these concerns themselves.

Azure API Management (APIM) — Azure's managed API gateway plus developer portal plus analytics. Formally, Microsoft.ApiManagement/service resource available in seven SKUs. Bundles a gateway, a developer-portal site, products / subscriptions, policy engine, and Application Insights integration. It matters because APIM is the canonical Azure answer for API integration — most exam questions on this LO route to it.

APIM Product — A logical bundle of APIs that consumers subscribe to. Like a TV channel package. Formally, a published collection of APIs gated by subscriptions. It matters because Products are the rate-limit and access-control unit — Premium API access vs Free tier is modelled as two Products.

APIM Subscription — An assigned subscription key that grants consumers access to a Product or API. Formally, an apimSubscription with a primary and secondary key. It matters because subscriptions are how APIM enforces "which app is calling".

APIM Policy — An XML expression that runs on inbound, backend, outbound, or on-error stages of a request. Formally, an <inbound>...</inbound> (etc.) policy document, scoped at global / product / API / operation. It matters because policies are how APIM transforms or rejects requests without backend code changes — JWT validation, rate limiting, header injection, retries.

Self-hosted gateway — A container that runs the APIM gateway data plane in a customer environment. Formally, a Docker image issued by Microsoft, configured against an APIM instance and run on AKS, Container Apps, or any Docker host. It matters for hybrid deployments where the backend is on-prem or in a different cloud — the gateway runs near the backend, the control plane (policies, portal, analytics) lives in Azure.

Application Gateway — Azure's regional L7 load balancer with WAF. Formally, Microsoft.Network/applicationGateways resource (v2 SKU, Standard or WAF) — supports path-based routing, SSL termination, autoscale, zone-redundancy. It matters as a lighter-weight alternative to APIM when you need WAF + path routing but not full API management.

Azure Front Door — Azure's global L7 edge service with WAF and AnyCast. Formally, Microsoft.Cdn/profiles (Standard / Premium) — global AnyCast edge, automatic failover, caching, WAF. It matters for global APIs needing low latency from many regions.

Versioning vs revisions — APIM lets you publish multiple versions ($v1$, $v2$) of an API exposed at different paths or headers, and lets you stage non-breaking changes as revisions. Formally, versions are caller-visible (/v1/orders vs /v2/orders); revisions are gateway-side staging (revision 2 promoted to current). It matters because the right versioning strategy is the single biggest determinant of API longevity.

Rate limit vs quota — Rate limit caps requests per short window (e.g., 100 rps); quota caps requests per long period (e.g., $10{,}000{,}000$/month). Formally, the policies rate-limit-by-key and quota-by-key. It matters because the two together model commercial tiers (a "Pro" tier might allow 500 rps and $50M$ req/month; "Free" allows 10 rps and $100k$ req/month).

Deep Dive

1. The APIM tier ladder

Azure API Management comes in seven SKUs. The exam tests SKU selection by capability.

[!TIP] Default to Standard v$2$ (or Standard) for most production deployments; reach for Premium v$2$ when you need multi-region, internal VNet integration (only Premium supports internal mode in classic tiers; Standard v$2$ and Premium v$2$ extend it), or zone redundancy.

[!WARNING] Developer tier has no SLA and is meant for dev/test. Several production teams have shipped on Developer to save cost and discovered the hard way that planned-maintenance restarts cause downtime — the tier is single-instance.

2. APIM policies — the configurable contract

Policies are XML expressions evaluated per request. The exam tests reading and writing them.

[!IMPORTANT] validate-jwt validates the token against the issuer's JWKS (public keys). It does not check authorization — that is a separate concern. Use validate-jwt for authentication, then policies (check-header, choose) for authorization decisions.

3. APIM vs Application Gateway vs Front Door — when each wins

The exam tests the choice among these three because they overlap visually but serve different purposes.

A common production stack for a public API is all three: Front Door at the edge (DDoS, global low latency, WAF), APIM for API management features (versioning, subscriptions, rate limiting per key), Application Gateway for internal L7 routing within the VNet to backend services. Smaller deployments collapse this — APIM alone handles most internal-mesh scenarios.

4. APIM networking — external vs internal mode

Two VNet modes:

Internal mode requires Premium (or Standard v$2$ / Premium v$2$ with newer support) and exposes APIM only via private IPs in the VNet. To make an internal APIM publicly accessible, pair with Application Gateway or Front Door as the public ingress.

[!NOTE] Internal mode + Premium multi-region = a private global API mesh. Combine with VNet peering or Private Link from the backend services to keep traffic on the Microsoft backbone.

5. Versioning, revisions, and lifecycle

APIM has two distinct change models:

A common pattern: create $v1$ as the public-facing version; create revisions of $v1$ as the backend evolves; when a breaking change is needed, create $v2$ leaving $v1$ in place; deprecate $v1$ on a schedule.

[!TIP] Use versions for breaking schema changes, revisions for adding optional fields or fixing implementation. Mixing them confuses consumers.

6. Self-hosted gateway — the hybrid pattern

For workloads where the backend is on-prem or in another cloud and you cannot route gateway $\to$ backend over public internet, deploy the self-hosted gateway near the backend.

The control plane (developer portal, policies, analytics) lives in Azure; the data plane (a container running the APIM gateway image) lives next to the backend. Requests sent to the self-hosted gateway are policy-evaluated locally and forwarded to backends without leaving the on-prem network.

Worked Examples

Easy — pick the right APIM tier

Problem. A team builds a public partner API expected to reach 300 partners over 2 years. Requirements: multi-region deployment in 3 regions, internal VNet mode (backends are on private subnets), zone redundancy, developer portal for partner self-service. Recommend an APIM tier.

Solution. Premium (or Premium v$2$). Only the Premium family supports multi-region deployment, internal VNet mode, and zone redundancy. Developer portal is included in all paid tiers. Multi-region adds units in additional locations; the global control plane stays in the primary region.

[!NOTE] Standard v$2$ is close on most features and cheaper, but does not support multi-region. If multi-region weren't needed, Standard v2 would be the answer.

Medium — gateway + policies for a partner API

Problem. A B2B API accepts JWT-bearer-authenticated requests from partner apps. Each partner has a daily quota of $1M$ calls and a 200 rps rate limit. Tokens are issued by the partners' own Entra ID tenants — the API trusts a list of allowed issuers. Configure APIM policies.

Solution. Two phases: (a) Create a Product Partner with a Subscription per partner organisation. (b) Apply this policy at Product scope:

[!TIP] Counter keys default per-subscription. For per-app counters, use @(context.User.Id); for per-IP counters, use @(context.Request.IpAddress). Pick the counter that matches the rate-limit's accounting unit.

Hard — design a global API mesh with hybrid backends

Problem. Contoso has APIs in three regions in Azure plus a critical legacy API on-prem in Frankfurt. Global clients should get low latency. The on-prem API must not be exposed to the internet. Recommend a topology.

Solution. Layered design:

Front Door routes to the nearest APIM region. For requests that target the on-prem API, that region's APIM policy uses <set-backend-service> to redirect to the self-hosted gateway URL inside the on-prem network (over ExpressRoute). The on-prem API is never exposed publicly.

Visual Explanations

Figure 1 — Decision flow for API integration

Figure 2 — APIM internal mode topology

Figure 3 — Quick chooser

Common Mistakes

❌ Myth: "Developer tier is fine for production at low traffic." ✅ Reality: Developer tier has no SLA and is single-instance. Planned maintenance causes downtime. Production should use Basic v$2$ minimum. Why it's tricky: Lower cost makes it tempting; teams discover the gap during the first patch window.

❌ Myth: "APIM and Application Gateway are interchangeable." ✅ Reality: APIM adds API management features (subscriptions, dev portal, versioning, policies). Application Gateway is L7 routing + WAF only. For partner-facing APIs needing subscriptions and quotas, APIM is required. Why it's tricky: Both terminate TLS and route by path; the API-management features are the differentiator.

❌ Myth: "Use validate-jwt for authorization." ✅ Reality: validate-jwt does authentication (is this token valid?). Authorization (does this caller have permission?) is enforced by additional policies on claims (<choose> over context.Request.Headers...), or by the backend. Why it's tricky: Tokens contain claims; teams conflate validating the token with checking those claims.

❌ Myth: "Front Door already does APIM's job." ✅ Reality: Front Door is a global edge with WAF and routing. It does not have API products, subscriptions, dev portal, per-key throttling, or transformation. Use both together for global APIs. Why it's tricky: Edge services advertise "global API frontend"; the API-management layer is still needed for management features.

Practice Exercises

🟢 Exercise 1. A team needs an API gateway with a developer portal and the ability to publish multiple API versions. Cost matters. Recommend a tier.

▶💡 Hint

Smallest tier with full management features and an SLA.

▶✅ Solution

APIM Basic v$2$ (or Basic classic). Both include the developer portal, products, subscriptions, versioning, revisions, and a 99.95% SLA. Standard adds higher capacity; Premium adds VNet internal mode and multi-region — neither is required here.

🟡 Exercise 2. An API behind APIM is called by mobile clients. The team wants to allow 100 rps per user with a $1M/$ day quota. The user identity is in the JWT sub claim. Write the policy.

▶💡 Hint

Use the JWT subject as the counter key.

▶✅ Solution

xmlCopy

<rate-limit-by-key calls="100" renewal-period="1" counter-key="@(context.Principal.GetClaim('sub') ?? 'anonymous')" /> <quota-by-key calls="1000000" renewal-period="86400" counter-key="@(context.Principal.GetClaim('sub') ?? 'anonymous')" />

🟡 Exercise 3. A bank's APIM must not be accessible from the internet. Its developer portal must be reachable by employees on the corporate network. Recommend a topology.

▶💡 Hint

Internal mode + a public ingress for the portal.

▶✅ Solution

APIM Premium (or Standard v$2$) in Internal VNet mode. Expose the developer portal via an Application Gateway with a private frontend that the corporate network reaches via ExpressRoute. APIM's gateway endpoint stays on a private IP; backends are reachable via Private Endpoint.

🔴 Exercise 4. A team deploys APIM Developer tier and goes live. Three weeks later there is a 20-minute outage during routine Azure maintenance. Diagnose.

▶💡 Hint

SLA and instance count.

▶✅ Solution

Developer tier has no SLA and is single-instance. Planned platform maintenance restarts the single instance, which is downtime. Migrate to Basic v$2$ or higher (multi-instance, SLA-backed). Production must not run on Developer.

🔴 Exercise 5. Front Door + APIM Premium are in the path. Partner reports a slow first byte ($\sim 1.5$ s) from Southeast Asia while Europe clients see $\sim 50$ ms. The backend is in West Europe. Diagnose.

▶💡 Hint

APIM is regional; only Premium does multi-region.

▶✅ Solution

APIM is deployed only in West Europe. Front Door's nearest edge in Asia routes to that region, so request latency includes a trans-Asia hop. Add an APIM Premium additional location in Southeast Asia (and replicate backends, or use Private Link to a regional backend). Front Door routes to the nearest APIM region instead of the only region.

🟢 Exercise 6. True or false: APIM Consumption tier supports VNet integration.

▶💡 Hint

Consumption is serverless and shared.

▶✅ Solution

False. Consumption tier runs on shared Microsoft infrastructure and does not support VNet integration. Workloads requiring VNet integration need Basic v2 (external), Standard v2 (external/internal preview), or Premium (external/internal).

🟡 Exercise 7. Design a Bicep snippet for APIM Standard v$2$ with system-assigned managed identity and a self-hosted gateway resource definition.

▶💡 Hint

Microsoft.ApiManagement/service + gateways child resource.

▶✅ Solution

bicepCopy

resource apim 'Microsoft.ApiManagement/service@2024-05-01' = { name: 'apim-prod' location: location sku: { name: 'StandardV2', capacity: 1 } identity: { type: 'SystemAssigned' } properties: { publisherEmail: 'platform@contoso.com' publisherName: 'Contoso' } } resource gw 'Microsoft.ApiManagement/service/gateways@2024-05-01' = { parent: apim name: 'gw-onprem-frankfurt' properties: { locationData: { name: 'Frankfurt-DC1' } description: 'Self-hosted gateway near legacy backend' } }

Summary & Concept Map

The headline takeaways from this lesson:

• APIM is the canonical Azure API integration service. Seven SKUs (Consumption, Developer, Basic, Basic v2, Standard, Standard v2, Premium, Premium v2) trade off capacity, VNet, multi-region.
• Default to Standard v$2$ or Premium v$2$ for new production. Avoid Developer for production; use Premium when you need multi-region or zone redundancy.
• Policies are the configurable contract. validate-jwt, rate-limit-by-key, quota-by-key, transforms, retries.
• Pair APIM with Front Door for global edge and with Application Gateway if you need additional internal L7 features.
• Internal mode + self-hosted gateway = hybrid mesh. APIM's control plane lives in Azure; the data plane runs near the backend.
• Versions for breaking changes, revisions for non-breaking iterations.