Blog

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:

XMLCopy

<policies>
    <inbound>
        <base />
        <check-header name="Authorization" failed-check-httpcode="401" failed-check-error-message="Not authorized" ignore-case="false">
        </check-header>
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
        <json-to-xml apply="always" consider-accept-header="false" parse-date="false" />
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>

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.
• Manage access to your APIs using policies.

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:

• Read API documentation.
• Try out an API via the interactive console.
• Create an account and subscribe to get API keys.
• Access analytics on their own usage.

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.

XMLCopy

<limit-concurrency key="expression" max-count="number">
        <!— nested policy statements -->
</limit-concurrency>

Log to Event Hubs

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.

XMLCopy

<mock-response status-code="code" content-type="media type"/>

Retry

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>

This unit provides a reference for the following API Management policies:

• Control flow – Conditionally applies policy statements based on the results of the evaluation of Boolean expressions.
• Forward request – Forwards the request to the backend service.
• Limit concurrency – Prevents enclosed policies from executing by more than the specified number of requests at a time.
• Log to Event Hubs – Sends messages in the specified format to an event hub defined by a Logger entity.
• Mock response – Aborts pipeline execution and returns a mocked response directly to the caller.
• Retry – Retries execution of the enclosed policy statements, if and until the condition is met. Execution repeats at the specified time intervals and up to the specified retry count.

Control flow

The choose policy applies enclosed policy statements based on the outcome of evaluation of boolean expressions, similar to an if-then-else or a switch construct in a programming language.

XMLCopy

<choose>
    <when condition="Boolean expression | Boolean constant">
        <!— one or more policy statements to be applied if the above condition is true  -->
    </when>
    <when condition="Boolean expression | Boolean constant">
        <!— one or more policy statements to be applied if the above condition is true  -->
    </when>
    <otherwise>
        <!— one or more policy statements to be applied if none of the above conditions are true  -->
</otherwise>
</choose>

The control flow policy must contain at least one <when/> element. The <otherwise/> element is optional. Conditions in <when/> elements are evaluated in order of their appearance within the policy. Policy statements enclosed within the first <when/> element are applied when the condition attribute is true. Policies enclosed within the <otherwise/> element, if present, are applied if all of the <when/> element condition attributes are false.

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.

In this challenge, you’ll write code that will use a formula to convert a temperature from degrees Fahrenheit to Celsius. You’ll print the result in a formatted message to the user.

Challenge: Calculate Celsius given the current temperature in Fahrenheit

1. Select all of the code in the .NET Editor, and press Delete or Backspace to delete it.
2. Enter the following code in the .NET Editor:C#Copyint fahrenheit = 94;
3. To convert temperatures in degrees Fahrenheit to Celsius, first subtract 32, then multiply by five ninths (5 / 9).
4. Display the result of the temperature conversion in a formatted messageCombine the variables with literal strings passed into a series of Console.WriteLine() commands to form the complete message.
5. When you’re finished, the message should resemble the following output:OutputCopyThe temperature is 34.444444444444444444444444447 Celsius.