Custom policies in Red Hat 3scale API Management, Part 1: Overview

API management platforms such as Red Hat 3scale API Management provide an API gateway as a reverse proxy between API requests and responses. In this stage, most API management platforms optimize the request-response pathway and avoid introducing complex processing and delays. Such platforms provide minimal policy enforcement such as authentication, authorization, and rate-limiting. With the proliferation of API-based integrations, however, customers are demanding more fine-tuned capabilities.

Policy frameworks are key to adding new capabilities to the API request and response lifecycle. In this series, you will learn about the Red Hat 3scale API Management policy framework and how to use it to configure custom policies in the APIcast API gateway.

Policy enforcement with 3scale API Management

APIcast is 3scale API Management's default data-plane gateway and policy enforcement point for API requests and responses. Its core functionality is to enforce rate limits, report methods and metrics, and use the mapping paths and security specified for each API defined in the 3scale API manager.

APIcast is built on NGINX. It is a custom implementation of a reverse proxy using the OpenResty framework, with modules written in Lua. Most NGINX functionality is implemented using modules, which are controlled by directives specified in a configuration file.

APIcast enforces API configuration rules that are set in the 3scale API manager. It authenticates new requests by connecting to the service API exposed by the API manager. It also allows access to the backend API and reports usage. Figure 1 presents a high-level view of APIcast in 3scale API Management's API request and response flow.

The default APIcast policy

A default APIcast policy interprets the standard configuration and provides API gateway functionality. The default policy acts as the API's entry point to the gateway and must be enabled for all APIs configured in 3scale API Management. The APIcast policy ensures that API requests are handled using the rules configured in the API manager. The configuration is provided to the APIcast gateway as a JSON specification, which APIcast downloads from the 3scale API Management portal.

Each HTTP request passes through a sequence of phases. A distinct type of processing is performed on the request in each phase. Module-specific handlers can be registered in most phases, and many standard NGINX modules register their phase handlers so that they will be called at a specific stage of request processing. Phases are processed successively, and phase handlers are called once the request reaches the phase.

To customize request processing, we can register additional modules at the appropriate phase. 3scale API Management provides standard policies that are pre-built as NGINX modules and can be plugged into each service's request.

Custom APIcast policies

In addition to the default policy, 3scale API Management provides custom policies that can be configured to each API. Using modules and configurations, these policies provide custom features for handling API requests and responses. Using custom modules makes the APIcast gateway highly customizable. It is possible to add custom processing and functionality on demand without modifying API gateway code or writing any additional code.

Note: See the chapter on APIcast policies in the 3sale API Management documentation for a list of all the standard policies that are available to be configured directly with APIcast.

Policy chaining

Policies must be placed in order of execution priority, and this placement is called policy chaining. Policy chains affect the default behavior of any combination of policies. The default APIcast policy should be part of the policy chain. If a custom policy needs to be evaluated before the APIcast policy, it must be placed before that policy in the chain. Figure 2 shows an example of the policy order as defined in the policy chain.

For example, take a scenario using a URL-rewriting policy to change the URL path from /A/B to /B. Placing the URL-rewriting policy before the APIcast policy ensures that the path is changed before gateway processing. Backend rules, mapping rules, and metrics all will be evaluated using the /B URL path.

If, on the other hand, the custom policy should be evaluated after the APIcast policy, you can reverse the order. As an example, if you wanted the mapping rules to be evaluated for /A/B, with the URL rewrite to /B applied afterward, then you would place the URL rewriting policy after the APIcast policy.

Configuring custom policies

There are two ways to add a new policy to an API. One option is to use the Policy section for each managed API in the 3scale API Management Admin Portal. All of the available policies are available to be added. If you prefer to use the Admin API, then you can provide the policy as a JSON specification, which you can upload to the service configuration using the provided REST API.

You also can copy a set of policies as part of the service configuration from one running environment to another using the 3scale Toolbox. To verify the set of policies applied to a specific API, you can download the current configuration and configuration history from the administration portal or using the provided REST API.

Check the video below for a demonstration of the policy configuration in 3scale API Management.

Conclusion

3scale API Management provides multiple options for configuring custom API policies. This article introduced the 3scale API Management policy framework, custom policies, and policy chaining. I also presented a brief example of how to configure and view policies in 3scale API Management. Future articles in this series will look at the available policies, and I will introduce the developer toolset that you can use to create your own custom policies. In the meantime, you can explore 3scale API Management by signing up for a free 3scale API Management account.