API Management instances usually have an internal cache, which is used to store prepared responses to requests. However, if you prefer, you can use a Redis-compatible external cache instead. One possible external cache system that you can use is the Azure Cache for Redis service.
You might choose to use an external cache because:
You want to avoid the cache being cleared when the API Management service is updated.
You want to have greater control over the cache configuration than the internal cache allows.
You want to cache more data than can be stored in the internal cache.
Another reason to configure an external cache is that you want to use caching with the Consumption pricing tier.
Optimal API performance is essential to most organizations. By using a cache of compiled responses in Azure API Management, you can reduce the time an API takes to answer calls.
Suppose there’s a need for the board gaming API to provide faster responses to requests. For example, users often request prices for various sizes of the board for games. API Management policies can accelerate responses by configuring a cache of prepared responses. When a request is received from a user, API Management checks to see if there’s an appropriate response in the cache already. If there is, that response can be sent to the user without building it again from the data source.
Here, you learn how to configure such a cache.
How to control the API Management cache
To set up a cache, you use an outbound policy named cache-store to store responses. You also use an inbound policy named cache-lookup to check if there’s a cached response for the current request. You can see these two policies in the following example:
It’s also possible to store individual values in the cache instead of a complete response. Use the cache-store-value policy to add the value, with an identifying key. Retrieve the value from the cache by using the cache-lookup-value policy. If you want to remove a value before it expires, use the cache-remove-value policy:
It’s important to ensure that, if you serve a response from the cache, it’s relevant to the original request. However, you also want to use the cache as much as possible. Suppose, for example, that the board games Stock Management API received a GET request to the following URL and cached the result:
This request is intended to check the stock levels for a product with part number 3416. The customer ID is used by a separate policy, and doesn’t alter the response. Subsequent requests for the same part number can be served from the cache, as long as the record doesn’t expire. So far, so good.
Now suppose that a different customer requests the same product:
By default, the response can’t be served from the cache, because the customer ID is different.
However, the developers point out that the customer ID doesn’t alter the response. It would be more efficient if requests for the same product from different customers could be returned from the cache. Customers would still see the correct information.
To modify this default behavior, use the vary-by-query-parameter element within the <cache-lookup> policy:
With this policy, the cache stores and separates responses for each product, because they have different part numbers. The cache doesn’t store separate responses for each customer, because that query parameter isn’t listed.
By default, Azure API Management doesn’t examine HTTP headers to determine whether a cached response is suitable for a given request. If a header can make a significant difference to a response, use the <vary-by-header> tag. Work with your developer team to understand how each API uses query parameters and headers so you can decide which vary-by tags to use in your policy.
Within the <cache-lookup> tag, there’s also the vary-by-developer attribute, which is required and set to false by default. When this attribute is set to true, API Management examines the subscription key supplied with each request. It serves a response from the cache only if the original request had the same subscription key. Set this attribute to true when each user should see a different response for the same URL. If each user group should see a different response for the same URL, set the vary-by-developer-group attribute to true.
You’re planning API Management policies for your board games company. You have three APIs:
The Board Pricing API: You manufacture boards of various sizes for partner companies to use with their games. Those partners can use this API to request a price estimate for manufacturing boards of different sizes.
The Stock Management API: Your staff uses a mobile app that calls this API to determine the stock level of your company’s games.
The Sales API: The website uses this API to place orders from customers for your company’s games.
You added the Stock Management API and the Sales API to an API Management product named Sales.
For the Board Pricing API, you want to make sure that all responses are sent in XML, even though developers wrote some operations to generate JSON text. The mobile app expects responses in XML, and the website expects responses in JSON.
You can use API Management policies to control the behavior of a deployed API without rewriting its code.
In your board game company, your APIs enable partner organizations to obtain price estimates, staff members to check stock levels, and customers to place orders. You want to address a particular issue with performance and investigate what else you can achieve with policies.
First, let’s look at what you can use policies to do.
What are policies?
In Azure API Management, administrators can use policies to alter the behavior of APIs through configuration. Developers design the primary functionality and behavior of an API by writing code. However, administrators can use policies to set limits, convert response formats, or enforce security requirements. In this module, we concentrate on using policies to set up and control a cache.
Policies are made up of individual statements, which are executed in order. The policy documents are XML structures, which contain elements that you can use to control the behavior of the API.
When do policies execute?
In Azure API Management, policies execute at four different times:
Inbound: These policies execute when a request is received from a client.
Backend: These policies execute before a request is forwarded to a managed API.
Outbound: These policies execute before a response is sent to a client.
On-Error: These policies execute when an exception is raised.
In the policy XML, there’s a separate tag for each of these execution times:
In this example, you can see that the policy checks inbound requests for a header named Authorization. If such a header isn’t present, the policy displays an error message.
This policy also translates any outbound responses in JSON format into XML.
To make an API available through an API gateway, you need to import and publish the API.
In the shoe company example, NorthWind Shoes wants to enable selected partners to be able to query inventory and stock levels.
Here, you learn how to import an API into Azure API Management, and how to make an API available to clients.
API
An API is a standardized way for organizations to expose specific data to potential developers or partners. For example, in the previous exercise you created an API to share information about products and inventory.
Making an API available starts with importing the API into API Management. You can then:
Test out your API by using the visualization tools in the API gateway.
Organizations often need to provide partners with access to data. This access must be controlled and managed.
In the shoe company example, retailers that stock NorthWind Shoes need to know how much stock they can order. Customers also like to know exactly when they’re going to get their order.
Here, you learn how Azure API Management works, and how to set up an API gateway.
Azure API management
The Azure API management service is hosted in the Azure cloud and is positioned between your APIs and the internet. Your API Management instance acts as an Azure API gateway.
When you publish your APIs, you use the Azure portal to control how particular APIs are exposed to consumers. You might want some APIs to be freely available to developers, for demo purposes, and access to other APIs to be tightly controlled.
Why use API Management?
For developers, API Management provides a range of benefits.
API documentation. Documentation of APIs enables calling clients to quickly integrate their solutions. API Management allows you to quickly expose the structure of your API to calling clients through modern standards like OpenAPI. You can have more than one version of an API. With multiple versions, you can stage app updates as your consuming apps don’t have to use the new version straight away.
Rate limiting access. If your API could potentially access a large amount of data, it’s a good idea to limit the rate at which clients can request data. Rate limiting helps maintain optimal response times for every client. API Management lets you set rate limits as a whole or for specific individual clients.
Health monitoring. Remote clients consume your APIs, so it can be difficult to identify potential problems or errors. API Management lets you view error responses and log files, and filter by types of responses.
Modern formats like JSON. Over the years, many different data exchange formats were used by APIs from XML to CSV and many more. API Management enables you to expose these formats using modern data models like JSON.
Connections to any API. In many businesses, APIs are located across different countries/regions and use different formats. API Management lets you add all of these disparate APIs into a single modern interface.
Analytics. As you develop your APIs, it’s useful to see how often your APIs are being called and by which types of systems. API Management allows you to visualize this data within the Azure portal.
Security. Security is paramount when dealing with system data. Unauthorized breaches can cost companies money, time lost in reworking code, and reputational loss. Security tools that you can use with Azure API management include OAuth 2.0 user authorization, and integration with Microsoft Entra ID.
Pricing tiers. API Management offers tiers with different capabilities for request throughput, service level agreement (SLA), network isolation, upgrade flexibility, and so on. When you create an Azure API management gateway, you choose the tier that meets your needs.
Certificates can be used to provide TLS mutual authentication between the client and the API gateway. You can configure the API Management gateway to allow only requests with certificates containing a specific thumbprint. The authorization at the gateway level is handled through inbound policies.
For your meteorological app, you have some customers who have client certificates issued by a certificate authority (CA) that you both trust. You want to allow those customers to authenticate by passing those certificates.
Here, you’ll learn how to configure API Management to accept client certificates.
Azure API Management helps organizations unlock the potential of their data and services by publishing APIs to external partners and internal developers. Businesses are extending their operations as a digital platform by creating new channels, finding new customers, and driving deeper engagement with existing ones. API Management provides the core competencies to ensure a successful API program through developer engagement, business insights, analytics, security, and protection. You can use API Management to take any backend and launch a full-fledged API program based on it.
To use API Management, administrators define APIs in the portal. Each API consists of one or more operations and can be added to one or more products. To use an API, developers subscribe to a product that contains that API, then call the API’s operations, subject to any usage policies that might be in effect. Common scenarios include:
Securing mobile infrastructure by gating access with API keys, preventing distributed denial of service (DDoS) attacks by using throttling, or using advanced security policies like JSON web token (JWT) validation.
Offering fast partner onboarding through the developer portal to independent software vendor (ISV) partner ecosystems, enabling them to build an API facade to decouple from internal implementations that aren’t ready for partner consumption.
Running an internal API program that offers a centralized location for the organization to communicate between the API gateway and the backend. Communications about the availability and latest changes to APIs would be on a secured channel with gated access based on organizational accounts.
Components of API Management
API Management is made up of the following components:
API gateway
The API gateway is the endpoint that:
Accepts API calls and routes them to the backend.
Verifies API keys, JWT tokens, certificates, and other credentials.
Enforces usage quotas and rate limits.
Transforms your API on the fly without code modifications.
Caches backend responses, where the capability is set up.
Logs call metadata for analytics purposes.
Azure portal
The Azure portal is the administrative interface where you set up your API program. You can also use it to:
Define or import API schema.
Package APIs into products.
Set up policies such as quotas or transformations on the APIs.
Get insights from analytics.
Manage users.
Developer portal
The developer portal serves as the main web presence for developers. From here, they can:
API Management provides the core functionality to ensure a successful API program through developer engagement, business insights, analytics, security, and protection. Each API consists of one or more operations, and each API can be added to one or more products. To use an API, developers subscribe to a product that contains that API, and then they can call the API’s operation, subject to any usage policies.
The forward-request policy forwards the incoming request to the backend service specified in the request context. The backend service URL is specified in the API settings and can be changed using the set backend service policy.
Removing this policy results in the request not being forwarded to the backend service. The policies in the outbound section are evaluated immediately upon the successful completion of the policies in the inbound section.
XMLCopy
<forward-request timeout="time in seconds" follow-redirects="true | false"/>
Limit concurrency
The limit-concurrency policy prevents enclosed policies from executing by more than the specified number of requests at any time. When requests exceed that number, new requests fail immediately with a 429 Too Many Requests status code.
The log-to-eventhub policy sends messages in the specified format to an event hub defined by a Logger entity. As its name implies, the policy is used for saving selected request or response context information for online or offline analysis.
XMLCopy
<log-to-eventhub logger-id="id of the logger entity" partition-id="index of the partition where messages are sent" partition-key="value used for partition assignment">
Expression returning a string to be logged
</log-to-eventhub>
Mock response
The mock-response, as the name implies, is used to mock APIs and operations. It aborts normal pipeline execution and returns a mocked response to the caller. The policy always tries to return responses of highest fidelity. It prefers response content examples, whenever available. It generates sample responses from schemas, when schemas are provided and examples aren’t. If examples or schemas aren’t found, responses with no content are returned.
The retry policy executes its child policies once and then retries their execution until the retry condition becomes false or retry count is exhausted.
XMLCopy
<retry
condition="boolean expression or literal"
count="number of retry attempts"
interval="retry interval in seconds"
max-interval="maximum retry interval in seconds"
delta="retry interval delta in seconds"
first-fast-retry="boolean expression or literal">
<!-- One or more child policies. No restrictions -->
</retry>