API-level policies

Edit online

webMethods API Gateway provides a policy framework that enables 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 run time. For example, a policy might instruct webMethods API Gateway to perform any of the following tasks and prevent malicious attacks:

  • Verify that API requests come from authenticated and authorized applications, by using the specified identifiers in the HTTP header.
  • Validate digital signatures in the security header of request and response messages.
  • 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. Send alerts to a specified destination when these performance conditions are violated.
  • Log the request and response messages, and the run-time performance measurements for APIs and applications.

You can enforce policies in an API in the following ways:

  • Global policy enforcement. This enforcement applies globally to all APIs defined in webMethods 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 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 based on their usage such as:

    For example, the Identify and access category of policies can be enforced on an API to specify the identifiers that are used to identify the application and authorize it against all applications that are registered in webMethods API Gateway.

  • Scope-level policy enforcement
    • 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 that are nested within a resource in the REST API.
    • Operation-level policy enforcement. Applicable only for SOAP APIs. This enforcement applies to one or more operations in the SOAP API.

How does policy enforcement work

When you apply policies globally (via global policies) and directly (via API-level and scope-level policies), the webMethods API Gateway determines the effective policies by considering API-level precedence, policy stages, policy priority, run-time constraints, and the status of applied global policies. 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:

  1. Global Policy Enforcement
  2. Method-level Policy Enforcement or Operation-level Policy Enforcement
  3. Resource-level Policy Enforcement
  4. API-level Policy Enforcement

If the API has the Identify and access policy applied through both globally and at the API-level, webMethods 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, the Identify and access policy is applied through a scope-level policy at the resource level and the API level, the Identify and access policy that is 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 that is 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. 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.

Variable framework

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 webMethods 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, 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

Aliases

webMethods 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 webMethods 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

Policy templates

webMethods 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.

Policy validation and dependencies

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

  • Any policy (for example, Log Invocation) that can appear in an API multiple times is allowed to appear multiple times.
  • For policies (for example, Require HTTP / HTTPS) that can appear only once in an API, API Gateway issues an error message.
  • For policies (for example, Monitor SLA) that are dependent and use another policy in conjunction (for example, Identify and Authorize Application) in an API, webMethods API Gateway prompts you with a warning message to include the dependent policy.

When you save an API, webMethods API Gateway combines the policies from all of the global and direct policies that apply to the API \(that is, at the API-level\) and generates what is called the effective policy for the API. For example, let's say 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. When you save the REST API, webMethods 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 webMethods API Gateway actually uses to publish the REST API.

When webMethods 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, webMethods API Gateway computes the effective API policy according to policy resolution rules. For example, an effective API policy can include only one Identify and Authorize Application policy. If the resulting policy list contains multiple Identify and Authorize Application policies, webMethods API Gateway shows the conflict by including an including a Conflict icon 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 .