Start with the big picture: what an API is, what a gateway does, and where this service sits.

An API, short for Application Programming Interface, is a set of rules that lets one program ask another program to do something. When a weather app on your phone shows today’s temperature, it does not measure the air itself. It sends a request over the internet to a weather service and receives the answer. The doorway through which it asks is the API. The program that asks is called the client, and the program that answers is called the backend or service. Most APIs on the web use a style called REST, where the client asks for things using simple web addresses and standard actions such as GET (read something) and POST (create something). The information travels in a common text format called JSON. Other styles exist too, such as SOAP, GraphQL, gRPC, and WebSocket, and Azure API Management supports several of them.

A gateway is a single entrance that sits between clients and many backends. Instead of each client knowing the address of every backend, the client talks only to the gateway. The gateway then forwards the request to the right backend, and brings the reply back. Because all traffic passes through one place, the gateway can do useful work on the way: check identity, limit speed, change the shape of messages, store answers for reuse, and write records.

Azure API Management, often shortened to APIM, is a fully managed Azure service that provides this gateway, together with tools to publish, secure, transform, maintain, and monitor APIs, and a website where developers can read about your APIs and try them. Fully managed means that Microsoft runs and maintains the underlying machines, so you focus on the APIs, not the servers. The backends that APIM protects can live anywhere: in Azure, in another cloud, or in your own data center.

Where the service came from

Microsoft built API Management as a product to help companies share their data and functions as APIs, safely and at scale. Over time it grew from a simple gateway into a full API platform with several pricing tiers, networking options, a developer portal, a self-hosted gateway for other environments, and in recent years features aimed at managing access to artificial intelligence services. Tiers and features change often, so check Microsoft’s current documentation when you plan a real deployment.

APIs multiply quickly. Without a front door, each one becomes a separate headache.

When a company has one small API, a team can protect it by hand. But successful companies soon have dozens or hundreds of APIs, built by different teams, in different languages, running in different places. Partners, mobile apps, websites, and other departments all want to use them. Five problems appear again and again.

API Management answers each of these. It applies the same security rules at one place. It limits the rate and total amount of calls per client. It records every call and shows charts. It hides backend details behind a stable public address, so the backend can move or change while clients notice nothing. It publishes a developer portal where people can sign up, read documentation, and try calls. And it lets you package APIs into products with plans and approval rules.

What it does not do

It helps to know the limits of the service, so that expectations stay realistic. API Management does not write your business logic, store your business data, or fix a poorly designed backend. It does not replace good testing, and it does not make an insecure application safe by itself. It also does not run your programs: it only receives calls and forwards them. Think of it as a skilled receptionist, not a replacement for the kitchen. The better your backends are designed, the more value you get from the gateway in front of them. Teams that treat the gateway as a magic fix often end up putting too much logic in policies, which later becomes hard to understand and maintain. Teams that use it for what it does best, shared security, traffic control, publishing, and visibility, enjoy a calmer and more reliable platform.

It is also worth remembering that adding any gateway adds one more step to every call. That step is small, usually a few milliseconds, but it is real, and it is another component that must be monitored, secured, and paid for. The benefits normally outweigh the costs once you have more than a few APIs or any external consumers, and this is why the service is most popular with growing organizations.

Learn these words once and the rest of the guide reads easily.

An APIM instance has three main parts that work together. Understanding the split between them explains almost everything else.

The first part is the gateway, sometimes called the data plane. The word “plane” simply means a layer of the system. The data plane is the layer that handles the actual traffic: it accepts a client’s request, runs the policies, calls the backend, and returns the answer. It is the busy road. In the managed service, Microsoft runs the gateway for you inside the instance, and in higher tiers it can run on several units or even in several regions at once.

The second part is the management plane. This is the layer you use to create and change things. When you add an API, edit a policy, or create a product, you are talking to the management plane. It stores your configuration and pushes it to the gateway. You reach it through the Azure portal (the web page where you manage Azure), through command-line tools, through automation templates, or through the management API. It is the manager’s office.

The third part is the developer portal. It is an automatically generated website that lists the APIs you choose to publish. People can sign up, read documentation made from your API definitions, try a call using a built-in test console, and get their subscription keys. You can change its design and content, or build your own portal if you prefer.

flowchart LR
    subgraph CLIENTS["Callers"]
        C1["Mobile app"]
        C2["Website"]
        C3["Partner system"]
    end
    subgraph APIM["API Management instance"]
        GW["Gateway - data plane"]
        MP["Management plane - configuration"]
        DP["Developer portal"]
    end
    subgraph BACKENDS["Backends"]
        B1["Azure Functions"]
        B2["App Service web app"]
        B3["On-premises service"]
        B4["Other cloud service"]
    end
    C1 --> GW
    C2 --> GW
    C3 --> GW
    GW --> B1
    GW --> B2
    GW --> B3
    GW --> B4
    ADMIN["API owners and DevOps"] --> MP
    MP -.->|"pushes configuration"| GW
    DEV["API consumers"] --> DP
    DP -.->|"reads API definitions"| MP
    

The figure reads from left to right for traffic: callers reach the gateway, and the gateway reaches the backends. Dashed lines show configuration and information flowing in the background. Notice that API owners never touch the road directly; they change the rules in the manager’s office, and the rules reach the road automatically.

Supporting Azure services

API Management comes in several tiers, from a pay-per-call option for small projects to enterprise tiers with many regions.

A tier is a package of features, capacity, and price. Choosing a tier is one of the first and most important decisions, because some features, such as joining a private network or running in several regions, exist only in certain tiers. The tier names have changed over the years, and Microsoft has introduced a newer family called the v2 tiers, so confirm the current list before deciding. The table below describes the general ideas.

Beyond the tier, you choose the number of units in the tiers that offer them. A unit is a block of gateway capacity. More units means more requests per second can be handled, and a higher monthly cost. Some tiers can autoscale, meaning they add or remove units on their own as load changes, within limits you set.

These four ideas describe what you publish, how you package it, and who may use it.

An API in API Management is a named collection of operations. Each operation describes one action: its web address path, its method (such as GET or POST), what it accepts, and what it returns. You can create an API in several ways. The simplest is to import an existing description. Common formats include OpenAPI (also called Swagger), a standard file that describes a REST API; WSDL for older SOAP services; and GraphQL schemas. You can also import directly from an Azure Function app, a Logic App, an App Service web app, or a Container App, and APIM reads the operations for you. If no description exists, you can build operations by hand. The gateway address your clients call is formed from the instance name and a suffix you choose for each API, and APIM maps it to the real backend address.

A product is how you offer APIs to consumers. A product holds one or more APIs and sets the terms: it can be open, requiring no key, or protected, requiring a subscription. It can require that an administrator approves each new subscription. It can set a limit on the number of subscriptions per user. It can carry its own policies, such as a rate limit for the “Free” product and a higher one for the “Premium” product. A product can be published, meaning visible in the developer portal, or draft, hidden while you prepare it. You can also restrict a product to certain groups of users, such as “Developers”, “Guests”, or “Administrators”, so only the right audience sees it.

A subscription links a consumer to a product or API and issues a pair of subscription keys, a primary and a secondary. The client sends one of them with each call, usually in a request header called Ocp-Apim-Subscription-Key. The gateway looks up the key, finds the subscription, checks that it is active, and applies the policies of that product. Two keys exist so that a consumer can rotate secrets without downtime: switch applications to the secondary key, then regenerate the primary. Subscriptions can have scope at the level of one API, one product, or all APIs.

Policies are small rules that run on every call. They turn a plain gateway into a powerful control point.

A policy is an instruction that API Management carries out while handling a request or a response. You write policies in an XML-based format, where each rule is a small element with settings. The beauty of policies is that they change how an API behaves without touching the backend code. Need to add a header, check a token, limit the rate, or hide a field? You write a policy. The backend never knows.

Every policy document has four sections, each running at a different moment of the journey. The inbound section runs when the request has arrived and before it is sent to the backend. The backend section runs around the actual forwarding to the backend. The outbound section runs after the backend has answered and before the response goes back to the client. The on-error section runs if something goes wrong at any stage, so you can return a friendly message and log the problem. Inside each section, policies run from top to bottom in the order you write them, so order matters.

flowchart LR
    REQ["Client request"] --> IN["Inbound - check, limit, change request"]
    IN --> BE["Backend - route and forward"]
    BE --> SVC["Backend service"]
    SVC --> OUT["Outbound - change response, cache, remove fields"]
    OUT --> RESP["Client response"]
    IN -.->|"any failure"| ERR["On-error - friendly message and log"]
    BE -.-> ERR
    OUT -.-> ERR
    ERR --> RESP
    

Scopes: where a policy applies

Policies can be attached at several scopes, from broad to narrow: the whole global instance, a workspace, a product, an API, or a single operation. A narrower scope inherits the rules of broader scopes through a special element that means “run the parent’s rules here”. This lets you place company-wide rules, such as mandatory logging, at the global level, then add specific rules at lower levels. Order and inheritance deserve care; a mistake can silently skip an important rule.

Expressions and reuse

Policies can include expressions, small snippets of logic that read the request or response and decide values at runtime. For example, an expression might read the user’s name from a token, or choose one backend or another based on a header. You can also store reusable settings in named values and reuse whole groups of rules as policy fragments, so that the same “standard security” block can be included in many APIs and changed in one place.

Follow a single call from a customer’s phone to your database and back, and see where each rule steps in.

Imagine a customer opens a shopping app and taps “My orders”. The app sends a request to the gateway address of your API Management instance. First, the request reaches the gateway over a secure connection. TLS, the technology behind the padlock in a web browser, encrypts the traffic so that nobody in between can read it. The gateway finds out which API and operation the address belongs to, by matching the path of the request against the list it holds in memory.

Next, the gateway checks whether a subscription key is required, and if so, whether it is valid and active. It then builds the effective policy for this call by combining the global, product, API, and operation policies in the right order. The inbound section runs: perhaps it validates a token that proves who the user is, checks the rate limit for this subscription, and adds a header that carries the user’s identity to the backend. If any step fails, the request stops here, and the on-error section creates a response such as “401 Unauthorized” or “429 Too Many Requests”. The backend never even hears about it, which is an important saving of work and risk.

If all checks pass, the gateway forwards the request to the backend, perhaps after rewriting the address and picking one of several backend copies. The backend does its work, and answers. The gateway receives the answer and runs the outbound section: it may remove secret fields, convert the format, add caching headers, or store the answer in its cache for the next caller. Finally the gateway sends the response to the client and writes records: a log line, a metric, and perhaps a trace. All of this typically adds only a few milliseconds, which is small compared with the time the backend needs.

sequenceDiagram
    participant C as Client app
    participant G as APIM gateway
    participant P as Policy engine
    participant E as Entra ID
    participant K as Cache
    participant B as Backend service
    participant L as Logs and metrics
    C->>G: HTTPS request with token and subscription key
    G->>G: Match API and operation, check subscription key
    G->>P: Build effective policy - global, product, API, operation
    P->>E: Validate token using public signing keys
    P->>P: Check rate limit and quota
    P->>K: Look for a stored answer
    alt Answer found in cache
        K-->>G: Cached response
    else Not cached
        G->>B: Forward request to backend
        B-->>G: Response
        G->>K: Store answer for next time
    end
    P->>G: Outbound rules - remove private fields, add headers
    G-->>C: Response
    G->>L: Write log, metric, and trace
    

There are dozens of built-in policies. Knowing the main families lets you solve most problems without extra code.

Policies fall into a few families by purpose. Here is a guided tour, described in words, since the exact XML is available in Microsoft’s reference.

Rate limit versus quota

Two policies are often confused. A rate limit controls speed: for example, no more than 100 calls per minute. It protects the backend from sudden bursts. A quota controls total amount over a longer time: for example, no more than 100,000 calls per month or 10 gigabytes of data per week. It enforces a business plan. Many products use both: a monthly quota for the contract, and a per-minute rate limit to prevent bursts. You can count by subscription, by caller IP address, or by a custom key such as a user identifier.

Mocking and transformation

A mock response policy returns a made-up example answer without calling any backend. It lets front-end developers start work before the real service exists. Transformation policies let you modernize without rebuilding. Suppose an old backend only speaks XML but new clients prefer JSON. A policy can convert the format both ways. Suppose a backend returns internal fields such as database IDs that you do not want to show; an outbound policy can remove them. Suppose the backend lives at a long awkward address; a rewrite policy can present a short clean one.

Retry and timeout

A retry policy tries again when a backend fails with a temporary error, using a delay that grows between attempts. It helps with short glitches, but must be used with care: retrying a request that creates a payment twice could charge a customer twice, so retry only operations that are safe to repeat. A timeout sets the longest time the gateway will wait for a backend, so that slow services do not hold up resources.

APIs must change over time. These two features let you change without breaking the people who depend on you.

Every API grows. New fields are added, old ones removed, rules tightened. If you change an API suddenly, every client that relied on the old behavior may stop working. API Management gives two tools to manage change, and it is important not to confuse them.

A revision is a safe working copy of an API for making non-breaking changes, such as fixing a description, adding an optional field, or adjusting a policy. You create a new revision, edit and test it using its own special address, and when you are happy you make it current, so that it replaces the old one for all callers. Older revisions are kept in a list, so you can see the history and, if needed, switch back. Revisions can have change log notes visible in the developer portal.

A version is a separate public edition of the API for breaking changes, such as removing a field or changing the meaning of a response. The old version continues to run exactly as before, so existing clients keep working, while new clients use the new version. Clients select the version in one of three ways: a segment in the path (such as /v1/orders and /v2/orders), a query string value (such as ?api-version=2), or a header. You group versions into a version set that tells APIM how to read the version. When the old version has had enough warning time, you retire it.

Two questions guard every API: who are you, and what are you allowed to do?

Authentication means proving who you are. Authorization means deciding what you are allowed to do once you are known. API Management supports several methods for each, and strong designs use more than one.

The most common modern setup uses OAuth 2.0, an industry standard for delegated access, and OpenID Connect, which adds user identity on top. In this setup, a client first signs in with an identity provider such as Microsoft Entra ID, and receives an access token. A token that follows the JWT (JSON Web Token) format is a signed piece of text that contains claims, which are facts about the user and the request: the user’s name, the audience the token was made for, the expiry time, and assigned roles or scopes. The client sends this token with each call. The gateway’s validate JWT or validate Entra token policy checks the signature using the provider’s public keys, confirms the audience and expiry, and may require certain claims. If the token passes, the gateway lets the call proceed. If not, the call is rejected before reaching the backend. This keeps the load and the risk away from the backend and gives you one consistent place to enforce rules.

The gateway to the backend

The gateway must also prove itself to the backend. One safe method uses a managed identity, an identity automatically created for the APIM instance in Microsoft Entra ID, with no password to store. The gateway gets a token for this identity and sends it to the backend, which trusts only calls that come with a valid token from the gateway. Other options include client certificates and shared secrets stored in Key Vault. There is also a feature called the credential manager that stores and refreshes connections to other services that need OAuth, so the gateway can call outside services on behalf of a user or application without developers handling tokens by hand.

flowchart TB
    U["User signs in"] --> IDP["Identity provider - Entra ID"]
    IDP -->|"access token"| APP["Client app"]
    APP -->|"call with token and key"| GW["APIM gateway"]
    GW --> V{"Token valid? Audience and claims correct?"}
    V -->|"No"| R["Reject with 401 or 403"]
    V -->|"Yes"| MI["Get managed identity token for backend"]
    MI --> BE["Backend accepts only gateway identity"]
    

An API nobody can find or understand is an API nobody uses. The portal is the shop window.

The developer portal is a website that API Management generates for you. It is designed for people who write programs that call your APIs. On it, a visitor can browse the list of APIs and products that you have published, read documentation built automatically from the API definitions, see example requests and responses in popular programming languages, and use an interactive test console to send real calls straight from the browser. Developers can sign up and sign in, using the built-in user system or an outside identity provider such as Microsoft Entra ID or social accounts. Once signed in, they can subscribe to a product, wait for approval if your rules require it, and see and regenerate their own keys. They can also view usage reports for their subscriptions.

The portal can be customized. A visual editor lets you change the layout, colors, logo, and text, add pages like “Getting started” or “Terms of use”, and show content from your own documentation. It supports publishing: you edit a draft, then publish the changes to the public site. For teams that want complete control, the portal can be self-hosted, meaning you take its source code and run it yourself with your own look and extra features. Since the portal is a public-facing website, protect it as you would any other website: control who can sign up, and keep sensitive APIs hidden by product visibility rules.

The gateway does not just forward calls. It can spread them across several copies and protect backends that are struggling.

A backend entity in API Management is a saved description of a service the gateway talks to: its address, the credentials to use, and its settings. By defining a backend once and referring to it by name, you can change the address in one place instead of in every API. Backends can be Azure services, services in other places, or even an Azure OpenAI deployment.

You can group several backends into a backend pool for load balancing, which means spreading the calls among several copies of the same service so no single copy is overloaded. The gateway can distribute calls in a round-robin way (each copy takes a turn), by weights (a stronger copy gets more), or by priority (use the main copy and switch to a secondary only when the main one fails). The same mechanism supports gradual rollouts: send ten percent of traffic to a new backend, watch the results, and increase.

A circuit breaker is a safety feature named after the switch in an electrical box. If a backend keeps failing, for example by returning many server errors within a short time, the breaker “trips” and the gateway stops sending calls to it for a set time, returning errors immediately or sending calls to other backends in the pool. This gives the struggling service time to recover instead of being hammered by retries, and protects clients from waiting for long timeouts. After the pause, the gateway tries a few calls, and if they succeed, the circuit closes again.

flowchart TB
    GW["APIM gateway"] --> POOL["Backend pool"]
    POOL --> B1["Backend copy 1 - priority 1"]
    POOL --> B2["Backend copy 2 - priority 1"]
    POOL --> B3["Backend copy 3 - priority 2 standby"]
    B1 -. "too many errors" .-> CB["Circuit breaker trips for a pause"]
    CB -.-> POOL
    

Where the gateway lives on the network decides who can reach it and what it can reach.

By default, an API Management instance has a public address on the internet. That is fine for public APIs, but many organizations need more control. A virtual network, or VNet, is your private network inside Azure. API Management offers several ways to connect to it, depending on the tier. In external mode, the gateway sits inside your network but still has a public address, so the internet can reach it, and it can reach private backends inside the network. In internal mode, the gateway has only a private address, so only callers inside your network, or those connected through VPN or ExpressRoute, can reach it. The newer tiers also support private endpoints, which give the instance a private address in your network for incoming traffic, and outbound integration into a network for calling private backends. Exact options differ by tier, so check the current comparison.

A common design for internet-facing APIs is to place Azure Application Gateway or Azure Front Door in front of an internal APIM. These services add a web application firewall, or WAF, which blocks well-known attacks such as injection of malicious code, and Front Door adds global routing and caching at the network edge. Behind them, APIM stays private and does the API-specific work of tokens, limits, and policies.

For high availability, the Premium tier supports availability zones, which spread the units across separate buildings within one Azure region, and multi-region deployment, which adds gateway units in other regions that share the same configuration. Clients can reach the nearest or healthiest region through a traffic manager such as Front Door. The management plane remains in the primary region, but the gateways in other regions continue to serve traffic with the last known configuration if the primary region has trouble.

flowchart TB
    USERS["Internet users"] --> FD["Front Door or Application Gateway with WAF"]
    FD --> APIM1["APIM gateway - Region A, internal"]
    FD --> APIM2["APIM gateway - Region B, internal"]
    APIM1 --> PB["Private backends in VNet"]
    APIM2 --> PB2["Private backends in VNet"]
    ONPREM["On-premises network"] -->|"VPN or ExpressRoute"| APIM1
    

Not every API lives next to the managed gateway. Two features let you place the gateway where you need it and share one platform among many teams.

The self-hosted gateway is a container version of the API Management gateway that you run yourself. A container is a lightweight, portable package that holds a program and everything it needs to run. You can place the self-hosted gateway in your own data center, in another cloud, or on an edge location such as a factory floor, usually using Kubernetes, a popular system for running containers, or Docker. The self-hosted gateway connects back to the management plane in Azure to receive configuration, and sends back some health and usage information. The policies, products, and developer portal remain the same, so API owners manage one set of rules for all gateways, managed and self-hosted.

Why would you want this? First, latency: if your backends sit in your own data center, sending every call up to an Azure gateway and back wastes time. Second, compliance: some rules demand that certain data never leaves a building or a country. Third, multi-cloud: your backends may be spread over several clouds, and you want a gateway close to each. Fourth, gradual modernization: legacy systems stay where they are, but wear a modern API front. The cost is that you must run, patch, scale, and monitor the self-hosted gateways yourself. A self-hosted gateway needs a tier that supports it, usually Premium or Developer, and it can continue to serve requests for a period even if it loses contact with the cloud, using its last known configuration.

Workspaces solve a different problem. In a large company, one central platform team may own the API Management instance, while many product teams want to publish their own APIs quickly. A workspace is a named area inside one instance, with its own APIs, products, subscriptions, named values, and policies, managed by a team with limited access. The platform team keeps control of the shared parts such as the gateway, the network, and global policies, while each team works independently inside its workspace. Workspaces can even have their own dedicated gateways in newer offerings, so a heavy user cannot slow down others.

Speed comes from not doing the same work twice. The gateway is a perfect place to remember answers and to manage costly new kinds of calls.

A cache is a place that stores copies of answers so they can be returned quickly the next time the same question is asked. API Management has a built-in cache, and you can connect an external cache such as Azure Cache for Redis for larger or shared storage across gateway units and regions. With caching policies you tell the gateway to store a response for a set time, and to vary the stored copy by things like query values, headers, or user. When the same request arrives within the time, the answer comes straight from the cache. The backend does no work, and the client gets a reply in a few milliseconds. This works best for data that changes slowly and is requested often, such as product catalogs, currency lists, and public reference data.

Caching needs care. Never cache personal or private responses in a way that allows one user to receive another’s data. Choose cache times based on how fresh the data must be, and plan how to remove stale items when data changes. Other performance habits include compressing responses, keeping policies light, placing the gateway in the same region as the backends, using connection reuse, and sizing units according to measured load.

The AI gateway use case

Many organizations now call large language models, which are AI systems that understand and generate text, such as those available through Azure OpenAI. These calls are costly, they are measured in tokens (small pieces of text that the model reads and writes), and they have limits on how many tokens can be used per minute. API Management is increasingly used as an AI gateway, a front door for such calls. With special policies, the gateway can limit the number of tokens per client, so one team cannot use up the shared quota; record how many tokens each team uses for cost sharing; spread calls across several model deployments and regions with load balancing and circuit breakers; keep a semantic cache, which can return a stored answer for a new question that means nearly the same as an earlier one; and apply content safety checks. Exact policy names and availability change quickly in this area, so check current documentation.

The gateway is the front line. Good security here protects every backend behind it.

Think of security in layers, like the layers of an onion. The outer layer is network protection: a web application firewall in front, a private network where possible, and restrictions on who can reach the management endpoints. The next layer is identity: strong token validation, client certificates for systems, and subscription keys for metering. The next is request checking: validate that each request follows the API’s shape, with the right fields, types, sizes, and values, and reject anything else. Content validation policies can compare a request’s body with the API’s schema, block oversized bodies, and reject unexpected parameters, which stops many injection attempts early. Finally comes data protection: hide secrets in named values backed by Key Vault, remove sensitive fields from responses, encrypt traffic in transit with modern TLS versions only, and turn off old weak protocols and ciphers.

The security community maintains a list called the OWASP API Security Top 10, describing the most common API weaknesses. These include broken object-level authorization (a user can read another user’s records by changing an ID in the address), broken authentication, excessive data exposure (returning more fields than needed), lack of rate limiting, broken function-level authorization (a normal user can call an admin operation), and misconfiguration. API Management helps with many of them: token validation for authentication, claim checks for authorization, outbound field removal for data exposure, rate limits and quotas for resource limits, and schema validation for malformed input. However, some weaknesses, such as a backend that forgets to check object ownership, must still be solved in the backend. The gateway is a strong layer, not a replacement for secure code.

Two more points deserve mention. First, management access: use Azure role-based access control to give people the smallest role they need, such as reader, contributor for specific tasks, or a role limited to a workspace, and turn on multifactor sign-in for administrators. Second, threat detection: Microsoft Defender for APIs can analyze traffic to API Management and warn about suspicious behavior, unused or unauthenticated APIs, and sensitive data exposure. Check current capabilities and pricing before relying on it.

You cannot improve or defend what you cannot see. API Management produces rich information, and Azure gives you places to read it.

Observability, the ability to understand a system from the signals it produces, rests on three kinds of signal. Metrics are numbers over time, such as total requests, failed requests, capacity used, and gateway response time. Logs are detailed records of individual events, such as one line per request with its address, status, and duration. Traces follow one request across many services, showing where the time went. API Management feeds all three into Azure Monitor and Application Insights.

What to watch

Logging has a cost, both in money and in speed. Logging every body of every request can expose private data and slow the gateway. Log what you need: identifiers, status codes, timings, and selected headers. Use sampling, which records only a percentage of calls, for high-volume APIs. Add a correlation identifier, a unique value passed from the client through the gateway to the backend, so that a single call can be followed across all systems.

Because everything passes through the gateway, its health matters enormously. Plan for the day something breaks.

The gateway is a single point of entry, which makes it both powerful and risky. The service is designed for high availability, and Microsoft offers a service level agreement, a promise of uptime, for most production tiers, with higher promises when you use multiple zones or regions. But your own design decides how well you survive trouble. The key ideas are redundancy (more than one of everything important), isolation (one failure should not spread), and graceful degradation (when part of the system fails, the rest keeps giving a reduced but useful service).

Back up the configuration of the instance regularly, either with the built-in backup feature or, better, by keeping everything as code in a repository, so you can rebuild in a new instance or region within hours. Practice the rebuild; an untested recovery plan is only a hope. Also design your clients to behave well: they should retry with growing delays and respect the “retry after” hint when told to slow down, rather than hammering a gateway that is already struggling.

Clicking in a portal does not scale. Mature teams treat their APIs and policies as code.

Editing settings by hand in the Azure portal is fine for learning, but it is risky for production: there is no review, no history, and no easy way to repeat the same setup in another environment. APIOps applies the habits of software delivery to APIs. The definitions of APIs, policies, products, and named values are stored as files in a repository such as GitHub or Azure Repos. Changes are made in a branch and reviewed by a colleague through a pull request. A pipeline then validates the files and deploys them to a test instance, runs automated tests, and after approval deploys to production. The same files can be used for every environment, with small environment-specific values replaced at deploy time.

Several tools support this. Azure Resource Manager templates, Bicep, and Terraform can create the instance and its configuration. The Azure command-line tools and the management API can script changes. A Microsoft-supported APIOps toolkit can extract an existing instance into files and publish them back. Policies can be stored as XML files and policy fragments. Automated tests can call the API in the test environment and check the answers, including security tests that confirm unauthorized calls are rejected. Linting tools can check API definitions against your company’s style rules, for example that every operation has a description and uses the agreed naming.

flowchart LR
    DEV["Developer edits API files and policies"] --> PR["Pull request and review"]
    PR --> CI["Pipeline - lint, validate, security checks"]
    CI --> TEST["Deploy to test instance"]
    TEST --> AUTO["Automated API tests"]
    AUTO --> APPROVE["Approval"]
    APPROVE --> PROD["Deploy to production instance"]
    PROD --> MON["Monitor and learn"]
    MON -.-> DEV
    

Costs depend mostly on the tier and the number of units, not on how many APIs you add. Choose the size to fit your traffic.

Pricing varies by tier. In the Consumption tier you pay per call, with a free monthly allowance, so a lightly used API costs very little, and an idle one costs nothing. In the other tiers, such as Developer, Basic, Standard, and Premium, you pay a fixed hourly price per unit, whether or not traffic arrives, so you pay for reserved capacity. Premium units cost far more than Basic or Standard units, and additional regions are billed as additional units. The newer v2 tiers have their own pricing structure. Because prices, units, free grants, and limits change, always use the official pricing page and the Azure pricing calculator for current numbers.

Other costs sit around the instance. Application Insights and Log Analytics charge by the amount of data stored. Azure Front Door or Application Gateway charge for their own capacity and data. A Redis cache has its own monthly price. Private networking, such as ExpressRoute or VPN gateways, adds cost. Data leaving Azure incurs network transfer charges. Self-hosted gateways need the compute you run them on. Defender for APIs and Azure OpenAI usage, if used, are billed separately.

Teams that have run many gateways keep finding the same good ideas and the same traps.

A short checklist from experienced teams, followed by the slips that cost beginners the most.

Mistakes that cost the most

Several products sit near API Management. Knowing the neighbors helps you place each one correctly.

Often the right answer is to combine tools. A frequent arrangement is Front Door at the global edge, Application Gateway with a firewall inside the region, API Management for API policies and products, and the backends behind it. Product names, features, and boundaries change, so check each vendor’s current documentation before deciding.

Three stories show how the pieces fit, followed by a quick guide to when this service is the right choice.

A simple decision guide

Azure API Management is the reception desk of your digital hotel: one front door that checks, shapes, limits, records, and presents your APIs.

We began with a hotel where guests talk to a reception desk instead of wandering into the kitchen. API Management plays that role for software. Its gateway handles the traffic, its management plane holds the rules, and its developer portal welcomes the people who use your APIs. We saw how products and subscriptions package access, how policies run in four sections to protect, reshape, cache, and record each call, and how tokens, certificates, and managed identities answer the questions of who you are and what you may do. We looked at versions and revisions for safe change, backend pools and circuit breakers for resilience, networking and regions for private and available designs, and self-hosted gateways and workspaces for hybrid and shared use. Finally we covered monitoring, cost, and APIOps, which turn a service into a well-run platform.