What are policies? Policies are pieces of configurations that invoke a specific type of action (depending on the type of policy) on a message. There are Built-in policies that come pre-packaged in the APIC solution. They are divided into five categories:
- Logic: These policies control the flow of the API by providing conditional coding aspects to your APIC such as if, switch, Operation-switch, and catch.
- Transforms: Provide the ability to transform payloads using various methods or manipulate headers. In Chapter 8, Message Transformations, you will work exclusively with these policies.
- Policies: Provide the ability to route, inspect, validate, log, set limits, and apply GatewayScript coding. This chapter will introduce you to some of these policies.
- Security: Apply client and user security as well as applying JWT capabilities. In Chapter 7, Securing APIs, you will work with these policies in detail.
- User-defined policies: Build your own policies. The user-defined policies feature is available only with the on-premises offering of APIC. In Chapter 12, User-Defined Policies, you will learn how to create your own custom policies.
These policies support your API use cases with data transformation, message routing, securing, validation, and logging. Essentially, these Policies provide building blocks to truly enhance your API’s capability. For instance, you may use these Policies to Map (transformation), Invoke (message routing), Validate (schema validation), apply Client Security/Validate JWT (for security), Log (to control logging information to the analytics server), and Throw (for exception handling).
It is worth mentioning that Catch is not a policy. Catch is implemented by IBM extensions to OAS. You will be introduced to the interplay of the Throw policy and Catch IBM extension through an example later in this chapter.
You should review the documentation for details of all the different Built-in Policies: https://www.ibm.com/docs/en/api-connect/10.0.1.x?topic=constructs-built-in-policies.
Policies are gateway type-specific. All Built-in policies, except for the Validate Username token policy, are available as part of DataPower API Gateway. There are several policies that are not available for DataPower Gateway (v5 compatible). You can review the Gateway specificity of the policies at https://www.ibm.com/docs/en/api-connect/10.0.1.x?topic=constructs-built-in-policies.
A sample screenshot to show you how policies are organized in an API is shown in Figure 4.18:
Figure 4.18 – Policies and Logic constructs
As you can see, you can apply multiple policies to a single API. To help your understanding of policies, you will be introduced to a few of the policies and how they supplement your API. In this chapter, we are focusing on the Invoke policy. It is the most important policy so you will learn about it now.
The Invoke policy
The Invoke policy is one of the most heavily used policy types and probably the most feature-rich too. It can often be used (depending upon the nature of the backend service provider) by keeping its default settings and by only specifying the URL property. But other than its basic usage, the Invoke policy provides many advanced properties to control the execution of the backend service call. You will learn about some of these advanced properties by implementing some new behavior.