Key concepts for API Management (APIM)

9.1 What is API Management?

A platform for publishing, securing, transforming, governing and analysing APIs at scale, made of three parts.

9.2 Core building blocks

The objects you create and manage in an APIM instance, and what each one is for.

// Calling an API published through APIM
builder.Services.AddHttpClient<PaymentsClient>(c =>
{
    c.BaseAddress = new Uri("https://contoso-apim.azure-api.net/payments/v1/");
    c.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", builder.Configuration["Apim:Key"]);
})
.AddStandardResilienceHandler();   // retries, timeouts, circuit breaker

9.3 Policies & the request pipeline

Policies are small rules that run in four stages of every call. They're inherited from the global scope down to individual operations.

Example policy

<policies>
  <inbound>
    <base />
    <!-- 1. Validate the OAuth token from Entra ID -->
    <validate-jwt header-name="Authorization" failed-validation-httpcode="401">
      <openid-config url="https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration" />
      <audiences><audience>api://payments</audience></audiences>
    </validate-jwt>
    <!-- 2. 100 calls per 60s per subscription -->
    <rate-limit-by-key calls="100" renewal-period="60" counter-key="@(context.Subscription.Id)" />
    <!-- 3. Call the backend with a managed identity (no secrets) -->
    <authentication-managed-identity resource="api://payments-backend" />
    <set-header name="x-correlation-id" exists-action="skip">
      <value>@(context.RequestId.ToString())</value>
    </set-header>
  </inbound>
  <backend><base /></backend>
  <outbound><base /><set-header name="X-Powered-By" exists-action="delete" /></outbound>
  <on-error><base /></on-error>
</policies>

9.4 Security in APIM

Secure both legs: consumer → gateway (front door) and gateway → backend (back door).

// Backend: trust only APIM. The token must be for this API and carry the "Gateway.Call" app role,
// which is assigned only to APIM's managed identity (authentication-managed-identity policy)
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(builder.Configuration.GetSection("AzureAd"));
builder.Services.AddAuthorizationBuilder()
    .SetFallbackPolicy(new AuthorizationPolicyBuilder().RequireRole("Gateway.Call").Build());

9.5 Versions vs revisions

Version = a breaking change that consumers choose to adopt. Revision = a safe, non-breaking change you test and then make current.

9.6 API lifecycle & APIOps

Treat APIs as products with a lifecycle, and treat APIM configuration as code.

<!-- .csproj: emit openapi/MyApi.json on every build, ready for lint + APIOps -->
<ItemGroup>
  <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.*" />
  <PackageReference Include="Microsoft.Extensions.ApiDescription.Server" Version="10.*" />
</ItemGroup>
<PropertyGroup>
  <OpenApiDocumentsDirectory>openapi</OpenApiDocumentsDirectory>
</PropertyGroup>

9.7 Monitoring & analytics

Use APIM's monitoring to see who calls which API, how fast it responds, and how often it fails.

• Built-in analytics: calls by API, product, subscription, geography; latency; errors.
• Application Insights: request telemetry, dependency tracking, end-to-end correlation (W3C traceparent).
• Azure Monitor / Log Analytics: gateway logs (ApiManagementGatewayLogs), alerts, capacity metric.
• Track: request volume, p95 latency (split gateway vs backend time), 4xx/5xx rates, 429s, capacity %.

builder.Services.AddOpenTelemetry().UseAzureMonitor();   // connection string from config
// APIM -> this API -> downstream calls now appear as one end-to-end transaction

9.8 Gateway patterns & the AI gateway

Standard ways to use a gateway, plus newer policies for fronting LLM APIs.

// A small .NET gateway: YARP + auth + rate limiting
builder.Services.AddReverseProxy()
    .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy"));  // routes + clusters
builder.Services.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorization();
builder.Services.AddRateLimiter(o => o.AddFixedWindowLimiter("standard", l =>
{
    l.PermitLimit = 100;
    l.Window = TimeSpan.FromMinutes(1);
}));

var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.UseRateLimiter();
app.MapReverseProxy();   // each route sets "AuthorizationPolicy" and "RateLimiterPolicy" in config

9.9 API Gateway vs Load Balancer vs Service Mesh vs ESB Added

These four often get mixed up. They sit at different points in the traffic path and solve different problems.