Azure API Management (APIM) is a fully managed gateway that sits in front of all your backend APIs. Instead of exposing your raw APIs directly to consumers, every request goes through APIM first. It handles security, rate limiting, transformation, monitoring, and documentation — all in one place.
I used APIM at Blue Yonder as the front door for all integrations on the SIAM platform. Every external system — Salesforce, ServiceNow, third-party vendors — called our APIs through APIM. It gave us one place to control, monitor, and secure everything.
Core Components
API Gateway receives all incoming API calls, applies policies before forwarding to the backend, and returns the response to the caller. This is the actual runtime component that handles every single request.
Developer Portal is an auto-generated documentation website where developers can discover and test your APIs, subscribe for API keys, and get started without calling your team. It is fully customizable with your branding.
Management Plane is the Azure Portal interface where you define APIs, products, policies, and users. You can import APIs directly from OpenAPI specs, WSDL files, Logic Apps, or Function Apps.
Analytics automatically logs every request with response times, error rates, and usage broken down by consumer. Built-in dashboards show you exactly what is happening across all your APIs.
APIs, Products and Subscriptions
Understanding this three-level hierarchy is the key to using APIM correctly.
An API is a group of related operations. For example an Orders API would contain GET /orders, GET /orders/{id}, POST /orders, and DELETE /orders/{id}.
A Product is a bundle of one or more APIs with its own subscription keys and policies. A Partner Product might contain the Orders API and Inventory API with a limit of 5000 calls per day and require approval to subscribe.
A Subscription is a key pair that grants access to a Product. Every caller gets their own subscription key. You can revoke individual keys without affecting any other consumer — critical for security incidents.
At Blue Yonder we had three products:
Internal Product — no rate limit, no approval needed
Partner Product — 5000 calls per day, requires approval
Public Product — 100 calls per day, open signup
Policies — The Heart of APIM
Policies are rules that run on every request or response. Written in XML, they are applied at four levels — Global, Product, API, or Operation — giving you incredibly fine-grained control.
Every request goes through four policy sections in order:
Inbound — runs before the request reaches your backend
Backend — controls how the backend is called
Outbound — runs before the response reaches the caller
On-Error — runs when any policy throws an exception
Here are the policies I used most in production:
Rate limiting — limits a caller to a set number of calls per time window. Returns 429 Too Many Requests when exceeded.
Quota — a hard cumulative limit over a longer period. Different from rate limiting — this counts total calls over the day rather than calls per minute.
IP filtering — only allow requests from specific IP address ranges. Essential for internal APIs that should never be called from the public internet.
Validate JWT — validates an Azure AD JWT token on every request. This is the most important security policy for external-facing APIs. It checks the token is valid, not expired, and contains the required claims.
Set header — adds or modifies a header on the backend request. We used this to pass internal API keys to backend services without ever exposing them to callers. The caller sends their subscription key. APIM validates it then adds the real internal key before forwarding.
Rewrite URL — maps the external URL to a different internal URL. Callers hit /orders/{id} while the backend receives /v2/orders/{id}. This lets you version your backend without breaking existing callers.
Cache response — caches GET responses for a configurable duration. We cached inventory lookups for 5 minutes which reduced backend load by 60 percent during peak hours.
Transform JSON to XML — converts a JSON request body to XML before forwarding to legacy backends. Modern callers send JSON, APIM handles the transformation transparently.
Authentication Options
APIM supports four authentication methods. You choose based on who is calling and what level of security you need.
Subscription Key is the simplest option. The caller passes a key in the Ocp-Apim-Subscription-Key header. Good for partner and internal system integrations where you control both ends.
OAuth 2.0 with Azure AD is the most secure option for external APIs. The caller gets a JWT token from Azure AD first then passes it as a Bearer token. APIM validates it using the validate-jwt policy. The token contains the caller identity, roles, and permissions. Use this for all user-facing apps and B2B enterprise integrations.
Client Certificate (mTLS) requires the caller to present a certificate instead of a password. APIM validates the certificate thumbprint. We used this at Blue Yonder for banking integrations where the highest security was required.
Basic Authentication passes username and password encoded as Base64. Only use this for legacy systems that support nothing else and always over HTTPS. Avoid for any new integration.
Named Values — Storing Secrets Safely
Named Values are APIM variables that store sensitive values like API keys and connection strings. You reference them in policies using double curly braces without ever hardcoding the actual value.
When you create a Named Value you mark it as secret. The value is encrypted at rest and never visible in the portal after saving. Best practice is to link Named Values directly to Azure Key Vault so secrets rotate automatically without any policy changes.
Versioning and Revisions
Versions handle breaking changes. You run v1 and v2 simultaneously at different URLs. Callers choose which version to use and you retire v1 only after all callers have migrated. No forced upgrades.
Revisions handle non-breaking changes. You create Revision 2 as a work in progress that is not live yet. Make and test your changes safely. Promote to live when ready. Instantly roll back to Revision 1 if something goes wrong.
This is how we deployed all APIM changes at Blue Yonder — zero downtime, zero caller impact, instant rollback capability.
Monitoring and Tracing
Every APIM request automatically logs the timestamp, caller IP, subscription key used, operation called, response time, and HTTP status code.
The most useful debugging tool is request tracing. Add the Ocp-Apim-Trace: true header to any request and the response includes a full trace of every policy step — exactly what data entered each policy, what came out, and how long it took. This saved me hours of debugging at Blue Yonder. You can see precisely which policy transformed what and where a request slowed down or failed.
Connect APIM to Application Insights and every request appears there automatically. Set alerts on error rate thresholds or response time degradation to catch problems before your callers do.
The Full Enterprise Integration Pattern
This is the complete architecture I built at Blue Yonder combining APIM with Logic Apps, Service Bus, and Azure SQL:
External System
|
| HTTPS with JWT token
v
Azure APIM
Validates JWT token
Applies rate limiting
Adds correlation ID header
Rewrites URL to internal format
|
v
Azure Logic App
Orchestrates business workflow
Calls ServiceNow and Salesforce APIs
|
v
Azure Service Bus
Reliable async messaging
Dead letter queue for failures
|
v
Azure App Service API
Processes the message
Updates the database
|
v
Azure SQL Database
Each layer has one job. APIM handles the front door. Logic Apps handles orchestration. Service Bus handles reliability. The API handles business logic. SQL handles persistence.
Key Lessons From Production
Always use Named Values for secrets — never hardcode API keys or passwords directly in policy XML.
Apply rate limiting at Product level not Global — different consumers have different needs. Partners get more calls than public users.
Use Revisions for every change — instant rollback has saved production incidents more than once.
Enable Application Insights from day one — you will need those logs the moment something goes wrong in production.
Use the Trace header during development — it shows exactly what every policy does to every request. Invaluable for debugging complex policy chains.
Set up the Developer Portal early — partners and consumers love self-service documentation. It reduces support requests dramatically.
Use validate-jwt for all external APIs — subscription keys alone are not enough. Tokens give you identity, roles, and expiry.
Add circuit breaker on every backend — protect your services from cascade failures when a downstream system goes down.
APIM Tiers
The Consumption tier charges per call with no monthly commitment — perfect for learning and low traffic APIs. The Developer tier costs around $50 per month with full features but no SLA — good for development and testing. Basic at around $150 per month is the entry point for production workloads. Standard at around $700 per month adds VNet support for enterprise use. Premium at around $2800 per month enables multi-region deployment and zone redundancy for global enterprise applications.
Summary
Azure API Management is the professional way to expose APIs in enterprise Azure architectures. One gateway to handle security, rate limiting, transformation, versioning, and monitoring for all your APIs.
Combined with Azure AD for authentication, Key Vault for secrets, Logic Apps for orchestration, and Service Bus for messaging — APIM completes the enterprise integration stack on Azure. If you are building serious integrations on Azure, APIM is not optional. It is the foundation everything else builds on.
Originally published at
https://www.techstackblog.com/
If you found this useful, follow me for more posts on Azure integration, C#, and cloud engineering.
