Policies

API Gateway provides a policy framework that enables you to program API behavior and implements specific limited management functions without writing any code. You can enforce a policy on an API to perform specific tasks, such as transport, security, logging, routing of requests to target services, and transformation of data from one format to another. You can also define a policy to evaluate and process the various API invocations at runtime. For example, a policy could instruct API Gateway to perform any of the following tasks and prevent malicious attacks:

Verify that the requests submitted to an API come from applications that are authenticated and authorized using the specified set of identifiers in the HTTP header to access and use the particular API.

Monitor a user-specified set of run-time performance conditions and limit the number of invocations during a specified time interval for a particular API and for applications, and send alerts to a specified destination when these performance conditions are violated.

You can enforce policies on an API at the following levels:

Global policy enforcement: This enforcement applies globally to all APIs defined in API Gateway. For example, the threat protection policies can be enforced for all APIs to protect against malicious attacks. For more information about threat protection policies, see webMethods API Gateway Administration Threat Protection Policies.

API-level policy enforcement. This enforcement applies to all resources and its nested methods of a REST API, or all operations of a SOAP API. These policies are further categorized into stages such as Transport, Identify and Access, Request and Response Processing, Routing, Error Handling, depending on their usage. For example, the Identify and access category of policies can be enforced on an API to specify the kind of identifiers that are used to identify the application and authorize it against all applications registered in API Gateway.

Resource-level policy enforcement. Applicable only for REST APIs. This enforcement applies to one or more resources and its nested methods in the REST API.

Method-level policy enforcement. Applicable only for REST APIs. This enforcement applies to one or more methods nested within a resource in the REST API.

How does the policy enforcement precedence work?

When you apply the policies both globally (through global policies) and directly (through API-level policies and scope-level policies) to an API, API Gateway determines the effective set of policies for that API by taking into account the precedence of policy enforcement at the API-level, the policy stages, the priority of policies, run-time constraints, and the status (activated or deactivated) of any applied global policy.

For example, consider an API is enforced with the identify and access policy at the following policy enforcement levels: global, API-level, and scope-level. The precedence of the policy enforcement that is effective for the API at runtime is as follows:

If the API has the identify and access policy applied both globally and at the API level, API Gateway does not show conflict. The identify and access policy applied through the global policy takes precedence and is processed at runtime.

Similarly for a REST API, identify and access policy is applied through a scope-level policy at the resource level and at the API level, the identify and access policy applied through the scope-level policy takes precedence and is processed at run-time.

When you apply a transport policy at the global level, the transport policy applied at the API level is in the disabled state. When you try deleting the API-level transport policy that is in the disabled state, an error displays and you are not allowed to delete this policy as the API-level transport policy is required and gets enforced when you deactivate the global policy.

All types of variables such as request, response, custom, custom-context, and system context variables are handled through the common framework called variable framework. The variable framework in API Gateway provides an option to extract variable values that can be used across stages. For example, you can use the extracted variable to transform request and response contents such as headers, query parameters, path parameters payload, and so on as per your requirement. With the variable framework, you can normalize the syntax and create a common template for accessing the various variable types. For details about the variable syntaxes to use, see Variable Framework.

API Gateway provides the capability of using aliases. An alias holds stage-specific property values that can be be shared by multiple policy configurations. Aliases referenced by policy configurations are substituted during runtime. Changing an alias value affects all referencing policies. Aliases are referenced through a name therefore alias names have to be unique within an API Gateway. The corresponding alias value is substituted in place of an alias name during run-time. Thus the same alias can be referred to in multiple policies and the change in a particular alias would affect all the policy properties. For more details about aliases and how to use them, see Aliases.

API Gateway provides policy templates, which are a set of policies that can be associated directly with an individual API. Policy templates provide the flexibility to alter the policy's configurations to suit the individual API requirements. These policy templates apply at the API level, and can be customized to suit the needs of a particular API. For more details about policy templates and how to use them, see Policy Templates.

When you enforce a policy to govern an API at run-time, API Gateway validates the policies to ensure that:

For policies (for example, Monitor SLA) that are dependent and use another policy in conjunction (for example, Identify & Authorize) in an API, API Gateway prompts you with a warning message to include the dependent policy.

When you save an API, API Gateway combines the policies from all the global and direct policies that apply to the API and generates what is called the effective policy for the API. For example, if your REST API is within the scope of two policies: one policy that performs a logging task and another policy that performs a security task and when you save the REST API, API Gateway automatically combines the two policies into one effective policy. The effective policy, which contains both the logging task and the security task, is the policy that API Gateway actually uses to publish the REST API.

When API Gateway generates the effective policy, it validates the resulting policy to ensure that it contains no conflicting or incompatible policies.

If the policy contains conflicts or inconsistencies, API Gateway computes the effective API policy according to policy resolution rules. For example, an effective API policy can include only one Identify & Authorize policy. If the resulting policy list contains multiple Identify & Authorize policies, API Gateway shows the conflict by including a Conflict (

) icon next to the name of the conflicting policies in the effective policy. For details about policy validation and dependencies, see Policy Validation and Dependencies.