APIM Policy Reference Guide

API Key

You can use the api-key policy to enforce API key checks during request processing, allowing only apps with approved API keys to access your APIs. This policy ensures that API keys are valid, have not been revoked or expired, and are approved to consume the specific resources associated with your API.

Security

Assign Attributes

You can use the assign-attributes policy to set variables such as request and execution context attributes. You can use it to retrieve initial request attributes after Transform headers or Transform query parameters policies and reuse them in other policies (Dynamic routing, RBAC, for example).

Transformation

Assign Content

You can use the assign-content policy to change or transform the request or response body's content. This policy is compatible with the Freemarker template engine, which allows you to apply complex transformations, such as transforming from XML to JSON and vice versa. You can access multiple objects from the template context by default — request and response bodies, dictionaries, context attributes, and more.

Transformation

Basic Authentication

You can use the basic-authentication policy to manage basic authentication headers sent in API calls. The policy compares the user and password sent in the basic authentication header to an APIM user to determine if the user credentials are valid.

To use the policy in an API, you need to configure:

Security

Cache

You can use the cache policy to cache upstream responses (content, status, and headers) to eliminate the need for subsequent calls to the back end. This policy is based on a cache resource, which aligns the underlying cache system with the API lifecycle (stop/start). Consumers can bypass the cache by adding a cache=BY_PASS_ query parameter or providing an X-Gravitee-Cache=BY_PASS HTTP header.

Performance

Dynamic Routing

The dynamic-routing policy dispatches inbound calls to different targets/endpoints or rewrites URIs.This policy is particularly useful for creating API Mashups.

Others

Generate HTTP Signature

HTTP Signature is an authentication method that adds a new level of security. Use this policy to generate an HTTP Signature with a set of headers, a max validity duration, and some other settings. The "Signature" authentication scheme is based on the model that the client must authenticate itself with a digital signature produced by either a private asymmetric key (e.g., RSA) or a shared symmetric key (e.g., HMAC).

Security

Generate JWT

You use the generate-JWT policy to generate a signed JWT with a configurable set of claims. This JWT can subsequently be forwarded to backend targets or used in another way. When a signed JWT is generated, it is put in the jwt.generated attribute of the request execution context. This is useful when, say, your front-end app uses only the API key and the back-end service uses JWT.

Security

Groovy

You can use the Groovy policy to run Groovy scripts at any stage of request processing through the gateway.

Others

HTML to JSON

You use the html-json transformation policy to transform the response content. This policy is based on the jsoup HTML parser. In APIM, you only need to provide your JSON field names with the associated selectors.

Transformation

HTTP Callout

You can use the callout-http policy to invoke an HTTP(S) URL and place a subset or all of the content in one or more variables of the request execution context. This can be useful if you need data from an external service and want to inject it during request processing. The result of the callout is placed in a variable called calloutResponse and is only available during policy execution. If no variable is configured, the result of the callout is no longer available.

Others

HTTP Signature

HTTP Signature is an authentication method that adds a new level of security. Under this policy, the consumer must send a signature using a secret key to temporarily identify the request and ensure that it's coming from the requesting consumer.

Security

IP Filtering

You can use the IP-filtering policy to control access to your API by filtering IP addresses. With CIDR, you can allow or deny a specific IP address or range of IP addresses. Whitelist mode excludes all IP addresses except those included in the whitelist.

Blacklist mode allows all IP addresses except the addresses included in the blacklist. The blacklist takes precedence, so if an IP address is included in both lists, the policy rejects the request. You can specify a host to be resolved and checked against the remote IP.

Security

JSON Threat Protection

You can use the json-threat-protection policy to validate a JSON request body by specifying limits for various JSON structures (such as arrays, field names, and string values). When an invalid request is detected (meaning the limit is reached), it will be considered a threat and rejected with a 400 BAD REQUEST.

Security

JSON to JSON

You can use thejson-to-json policy to apply a transformation (or mapping) on the request, response, and/or message content. This policy is based on the JOLT library.

Transformation

JSON to XML

You can use the json-xml policy to transform JSON content to XML content.

Transformation

JSON Validation

You can use the json-validation policy to validate JSON payloads. This policy uses the JSON Schema Validator. It returns 400 BAD REQUEST when the request validation fails and 500 INTERNAL ERROR when the response validation fails, with a custom error message body. It can inject processing report messages into request metrics for analytics.

Others

JSON Web Signature

Before sending the API call to the target backend, you can use the jws-validator policy to validate the JWS token signature, certificate information, and expiration date.

Security

JWT

You can use the JWT policy to validate the token signature and expiration date before sending the API call to the target backend.

Security

Keyless

This security policy does not block requests as it considers them valid by default.

Security

Latency

You can use the latency policy to add latency to the request or the response. For example, if you configure the policy on the request with a latency of 100ms, the gateway waits 100ms before routing the request to the backend service.

This policy is particularly useful in two scenarios:

Others

Metrics Reporter

This policy allows you to push the request metrics to a custom endpoint. Running this policy ensures the complete response is sent to the initial consumer. You can configure the payload to send to the custom endpoint by using the Freemarker template engine.

Others

Mock

You can use the mock policy to create mock responses when a consumer calls one of your services. This means you do not have to provide a functional backend when you create your API, giving you more time to think about your API contract.

Others

OAuth2

Using token introspection, you can use the oauth2 policy to check access token validity during request processing. If the access token is valid, the request is allowed to proceed. If not, the process stops and rejects the request. The access token must be supplied in the Authorization HTTP request header.

Security

OpenID Connect UserInfo

Use the policy-openid-userinfo to get the OpenId Connect user info from an OAuth2 resource through its UserInfo endpoint.

Security

Override HTTP Method

You can use the override-http-method policy to override the HTTP method provided by the initial consumer with a new configured value when the inbound request is sent to the backend API.

Transformation

Rate Limiting

There are three rate-limit policies:

Others

Regex Threat Protection

You can use the regex-threat-protection to extract information from a request (headers, path, query parameters, body payload) and evaluate that content against pre-defined regular expressions. If any content matches the specified regular expression, the request is considered a threat and rejected with a 400 BAD REQUEST. The policy injects processing report messages into request metrics for analytics.

Security

Request Content Limit

You can use the request-content-limit policy to specify the maximum time allowed for request content. This limit is compared to the content length header of the request.

Others

Resource Filtering

You can use the resource-filtering policy to filter REST resources. By applying this filter, you can restrict or allow access to a specific resource determined by a path and a method (or an array of methods).

This policy is mainly used in plan configuration to limit subscriber access to specific resources. A typical usage would be to allow access to all paths (/**) but in read-only mode (GET method).

Others

REST to SOAP

You can use the rest-to-soap policy to expose the SOAP backend service as a REST API. The policy will pass the SOAP envelope message to the backend service as a POST request. SOAP envelopes support Expression Language to provide dynamic SOAP actions.

Transformation

Retry

You can use the retry policy to replay requests when experiencing backend connection issues or if the response meets a given condition.

Others

Role Based Access Control

You can use the role-based-access-control policy (RBAC policy) to control access to a resource by specifying the required roles to access it.

The policy can be configured to either:

Security

SSL Enforcement

You can use the ssl-enforcement policy to filter incoming SSL requests. It allows you to restrict or allow access only to requests with client certificate authentication or only to a subset of valid clients.

Security

Traffic Shadowing

Traffic shadowing allows you to copy traffic to another service asynchronously. This policy duplicates requests and sends them to the target, an endpoint defined at the API level. The request can be enriched with additional headers.

Others

Transform Headers

You can use the transformheaders policy to override HTTP headers in incoming requests or outbound responses. You can override the HTTP headers by:

Transformation

Transform Query Parameters

You can use the transformqueryparams policy to override incoming HTTP request query parameters. You can override the HTTP query parameters by:

Transformation

URL Rewriting

You can use the url-rewriting policy to rewrite URLs from an HTTP response header or body.

Transformation

Validate Request

You can use the request-validation policy to validate an incoming HTTP request according to defined rules. A rule is defined for an input value. This input value supports Expression Language expressions and is validated against constraint rules. For example, it can be used after OpenID Connect UserInfo policy to vaidate who is making the request.

Others

XML to JSON

You can use the xml-json policy to transform XML content to JSON content.

Transformation

XML Threat Protection

You can use the xml-threat-protection policy to validate an XML request body by limiting XML structures such as elements, entities, attributes and string values. When an invalid request is detected (meaning the limit is reached), the request will be considered a threat and rejected with a 400 BAD REQUEST.

Security

XML validation

You can use the xml-validation policy to validate XML using an XSD schema. This policy uses javax.xml. When validation fails, a 400 BAD REQUEST error is received with a custom error message body. It also injects processing report messages into request metrics for analytics.

Others

XSLT Transformation

If your backend exposes XML content, you can use the XSLT policy based on the Saxon library to apply an XSL transformation to an incoming XML request body or to the response body.

Transformation

Assign Metrics

You can use the assign-metrics policy to push extra metrics in addition to the natively provided request metrics. These metrics can then be used from analytics dashboards to create custom widgets and, optionally, apply aggregations based on their value.

Transformation

Data Logging Masking

You can use the data-logging-masking policy to configure rules to conceal sensitive data. You can use JSON-path, XML-path, or a regular expression to identify the information to hide.

Others