API Manager custom policies

API Manager custom policies are optional policies developed in Policy Studio that can be applied to APIs registered in API Manager. For example, these include custom policies for inbound security, request or response processing, or routing.

This topic describes the API Manager HTTP request flow, and explains the different custom policies that you can add at different stages in the flow. It also gives examples of why you would use these custom policies and explains what happens when they are executed at runtime.

For details on how to configure policies in Policy Studio, see the API Gateway Policy Developer Guide.

API Manager HTTP request flow

When custom policies are configured for front-end APIs in API Manager, the request flow is in the following order:

  1. Client request
  2. Default inbound security or optional inbound security policy
  3. Optional request policy
  4. Outbound authentication profile and/or default routing or optional routing policy
  5. Back-end service
  6. Optional response policy
  7. Client response

This HTTP client request flow is shown in the following swim lane diagram:

API Manager HTTP Request Flow

The API Manager policy flow is described as follows:

  • When the client makes an API call to API Manager, and the API request is first verified. If the request is not valid or not permitted, API Manager returns an HTTP error such as:
    • HTTP 400 Bad Request
    • HTTP 404 Not Found
    • HTTP 405 Method Not Allowed
    • HTTP 429 Too Many Requests
  • When the API request has been verified, the optional custom inbound security policy is invoked if configured. This means that the default security no longer applies, and all authentication and access to the API by the API Manager organization must be provided by the custom policy. When inbound security returns false, API Manager returns an HTTP error such as:
    • HTTP 401 Unauthorized
    • HTTP 403 Authentication Failed
    • HTTP 500 Internal Server Error
  • If an optional request policy is configured, it could perform some customization on the client request, which is controlled by the API Manager administrator, before sending it to the routing policy.
  • The default routing uses a Connect to URL filter to route to the back-end service. If you need to customize this, you can configure an custom routing policy instead.
  • The client request is then routed to the back-end service.
  • When the response is returned from the back-end service to API Manager, if an optional response policy is configured, it processes the response and can customize it as needed before the response is returned to the client.

API Manager custom policies

The order of execution of the different custom policies is as follows:

API Manager Custom Policy Flow

Custom policy execution

The following general rules apply when API Manager custom polices are executed:

  • If a filter in a custom policy is aborted, the execution flow is interrupted, and an HTTP 500 Internal Server Error is returned to the client. You can add an API Gateway Generic Error fault handler filter to a policy, but this will print the stack trace and the execution flow will continue to the next policies.
  • If a filter in a custom policy returns false, and there is no false flow defined in the policy, an HTTP 500 Internal Server Error is returned to the client. However, in this case, you can customize the false flow and return a custom HTTP code and error message. For example, you could use a Set Attributes or Copy/Modify Attributes filter to set the following message attributes when your request policy fails:
  • request.policy.failure = true
    request.policy.httpcode = 403
    request.policy.error.msg = something happened

  • You can then use a custom routing policy to control processing and routing to the back-end. For example, you can test the value of the request.policy.failure attribute to check if the request policy succeeded, and then route to back-end. If the request policy failed, you can stop processing, and use the values from request.policy.httpcode and request.policy.error.msg to create a custom message that is reflected to the end user.
  • You can define API Manager fault handler policies at the API Manager, API, and method level. However, if a local fault handler is configured for any custom policies, and an exception occurs in any of these policies, the local fault handler is executed for the exception. The flow then continues as if the exception did not occur, which may not be the desired behavior.
  • A workaround is to define a policy that acts as the fault handler using an API Gateway Policy Shortcut filter, and for that policy to return false. This ensures that any API Manager fault handler policies also get executed. For more details, see Add API Manager fault handler policies.
  • In the case of failure, an HTTP 500 Internal Server Error response code is always returned for a SOAP 1.1 response, or an HTTP 400 and HTTP 500 for a SOAP 1.2 response with the corresponding SOAP fault code in the SOAP response body.

Custom policy types

These API Manager custom policies are described as follows:

Custom Policy Description
Inbound Security Policy

Enables you to configure optional security policies to perform custom authentication for front-end APIs. API Manager provides a number of built-in authentication policies (for example, API key, OAuth, and SSL), which you can select when creating front-end APIs. You can extend the list of built-in authentication mechanisms by using the Inbound security > Invoke policy setting to select a custom authentication policy that has been developed in Policy Studio.

For example, you could configure a custom authentication policy that uses CA SiteMinder to authenticate client requests. In addition, custom authentication policies can specify a message displayed in the API Catalog informing application developers of the authentication mechanism to use when accessing the API. By default, no inbound security policies are configured. When you configure an inbound security policy, this means that the default security no longer applies, and all authentication and access to the API by the API Manager organization must be provided by the custom policy.

Note The inbound security policy must set the authentication.subject.id message attribute to the client ID set in the external credentials of the client application, and return true for successful authentication. By default, Invoke policy > Use client registry specifies that authentication.subject.id must match one of the application's external credentials in the API Manager client registry. This setting is also required for API Manager to check if the organization has access to the API. If you do not select this setting, the API will have no client information, and API Manager will not check the organization access.

Custom policies developed for inbound security must always end on true or false. Returning true means successful authentication, and returning false means failed authentication. In this way, these policies behave like API Gateway Policy Shortcut filters, where the result is passed back to the calling policy and handled there. For more details, see Configure Advanced Inbound settings.

Global Request Policy

Enables you to configure optional global enforcement policies for front-end APIs (for example, security, compliance, or governance policies executed as part of every API call). By default, no global policies are configured.

When global request policies have been configured in Policy Studio, the API administrator can select a global request policy on the API Manager settings page. The selected global request policy is executed after inbound security but before any request, routing, or response policies configured for the front-end API. For more details, see Enforce API Manager global policies.

Request Policy

Enables you to configure optional request processing policies for front-end APIs. For example, you could use a configured policy to check request messages for authentication or authorization. By default, no request policies are configured.

When request policies have been configured in Policy Studio, you can then apply them in API Manager on the Frontend API > Outbound > Advanced page. The selected request policy is executed after inbound security and any global request policy, but before any routing or response policies configured for the front-end API. For more details, see Configure Advanced Outbound settings.

Routing Policy

Enables you to configure custom routing policies for front-end APIs. For example, you could use a configured policy to route to a specific back-end JMS service. By default, no routing policies are configured, and a default routing policy template is used. For more details, see Add custom API Manager routing policies.

When routing policies have been configured in Policy Studio, you can then apply them in API Manager on the Frontend API > Outbound > Advanced page. The selected routing policy is executed after any request policy and before any response policy configured for the front-end API. For more details, see Configure Advanced Outbound settings.

Response Policy

Enables you to configure optional response processing policies for front-end APIs. For example, you could use a configured policy to validate or transform outbound response messages. By default, no response policies are configured.

When response policies have been configured in Policy Studio, you can then apply them in API Manager on the Frontend API > Outbound > Advanced page. The selected response policy is executed after any routing policy configured for the front-end API, but before any global response policy. For more details, see Configure Advanced Outbound settings.

Global Response Policy

Enables you to configure optional global enforcement policies for front-end APIs (for example, security, compliance, or governance policies executed as part of every API call). By default, no global response policies are configured.

When global response policies have been configured in Policy Studio, the API administrator can select a global response policy on the API Manager settings page. The selected global response policy is executed last after any response policy configured for the front-end API. For more details, see Enforce API Manager global policies.

Fault Handler Policy

Enables you to configure optional fault handler policies that are applied to front-end API invocations. The configured fault handler is executed when an error or exception occurs during the API Manager runtime API invocation. The API Manager Default Fault Handler policy is configured by default.

When fault handler policies are configured, an API administrator can select a global fault handler policy for all front-end APIs on the API Manager settings page. API developers can also select fault handler policies for specific front-end APIs and API methods on the Frontend API > Outbound > Advanced page. For more details, see Add API Manager fault handler policies.

Note   These custom policies apply to APIs registered using API Manager only, and do not apply to policies registered using Policy Studio. These custom policies enable policy developers to implement enterprise-specific policies in Policy Studio that can be applied to multiple APIs in API Manager.

Further information

For more details, see the following related topics:

Related Links