Implement APIs

After you create an API, apply policies to configure the request and response flows.

Policies in the request flow secure, throttle, route, manipulate, or log requests before they reach the backend service; polices in the response flow manipulate and log responses before they reach the requesting client. See Configure the API Request URL and Configure the Service Request URL to configure mandatory policies. These are added for you when you create an API in the UI.

You must have the Manage API grant for an API to apply or configure policies for it.

Topics

Understand Policies

You apply any number of policies to an API definition to secure, throttle, route, or log requests sent to your API. Depending on the policies applied, requests can be rejected if they do not meet criteria you specify when configuring each policy.

Policies are executed in the order they appear on the Request and Response tabs. A policy can be placed only in certain locations in the execution flow. Most policies can be placed in the request flow; only the redaction, logging, and groovy script policies can be placed in the response flow.

Oracle API Platform Cloud Service provides these types of policies:

Security: policies that determine who can send requests to your services. See these topics to learn more:
Traffic Management: policies that manage the volume of traffic sent to your services. See these topics to learn more:
Interface Management: policies that manage the service interfaces clients are permitted to access. See these topics to learn more:
Routing: policies that route requests to different service URLs depending on the requesting application, the resource requested, and other conditions. See these topics to learn more:
Other: policies not belonging to one of the above categories. See these topics to learn more:

Configure the Request Pipeline

You can add policies in the request flow between the request from a client and when the request is sent to the backend service.

When viewing an API in the Management Portal, click the Request tab to view a top-down visual representation of the request flow.

The API Request URL is the endpoint clients send requests to. This represents when an endpoint deployed to a gateway receives a request. You apply any number of policies between the gateway receiving a request. Policies execute in order, with the uppermost policy first, followed by the next policy, and so on, until the request is rejected or sent to the backend service if all policy conditions are met. The Service Request URL is where requests meeting the policy criteria are sent to your service.

Configure the Response Pipeline

You can add policies in the response flow between the response from a backend service and when the response is sent to the client.

When viewing an API in the Management Portal, click the Response tab to view a top-down visual representation of the response flow.

The Service Response and API Response entries can’t be edited. The Service Response and API Response entries are visual representations of the response sent from the backend service to the gateway and the response sent to the requesting client, respectively.

The service response happens first. The response from the backend service is always the first entry in the outbound flow. You can place additional policies in this flow. Policies execute in order, with the uppermost policy first, followed by the next policy, and so on, until the response is sent back to the client.

Policy Placement

You can place policies only in specific positions in your API implementations.

The following table describes where and in what order polices can be placed in the request and response flows for your APIs. Because policies are executed sequentially, the order in which they appear is important. Each policy is assigned a number, where 1 the first policy and 100 is the last policy in the flow. The API Request is always first in the request flow (with a value of 5) and the Service Request is always last (with a value of 100). Valid placement for polices within this range is determined by its placement value. For example, key validation policies (with a placement value of 10) can only be placed after API Requests but before all other polices (their values greater than 10).

Policies with the same value can be placed in any order relative to their position in the flow. For example, interface filtering and header validation polices can be placed in any order as long as they are placed after a key validation policy but before a header-based routing policy. Policies with multiple values, such as the Groovy Script policy, can be placed in any of the listed positions.

Policy Type	Valid Request Flow Placement	Valid Response Flow Placement
API Request	5	-
Service Response	-	110
Key Validation	10	-
Basic Auth	11	-
Oauth 2	11	-
API Rate Limiting	30	-
API Throttling - Delay	30	-
Application Rate Limiting	30	-
Interface Filtering	30	-
Service Callout	30	-
Method Mapping	30	-
CORS	30	-
Redaction	30	150
Header Validation	30	-
IP Filtering	30	-
Header Field Filtering	30	-
Request Payload Validation	30	-
Service Level Authorization	40	-
REST2SOAP	40	130
Header Based Routing	50	-
Resource Based Routing	50	-
Application Based Routing	50	-
Gateway Based Routing	50	-
Groovy Script	30,40,50	150
Logging	30,40,50	150
API Response	-	200
Service Request	100	-

Apply Policies

Apply policies to an API to secure, throttle, route, or log requests sent to it. Depending on the policies applied, requests can be rejected if they do not meet criteria you specify when configuring each policy.

Topics

You must have the Manage API grant for an API to apply or configure policies for it.

Configure the API Request URL

The API Request URL is the endpoint to which users or applications send requests for your API. You configure part of this URL.

The full address to which requests are sent consists of the protocol used, the gateway hostname, the API Request endpoint, and any private resource paths available for your service. An example API Request URL is http://example.com:8001/Energy1/estimate/4859634, where:

http is the protocol over which the gateway receives requests.
http://example.com:8001/ is the hostname and port of the gateway node instance to which this API is deployed.
Energy1 is the API endpoint you configure. Anything beyond the API endpoint is passed to the backend service.
/estimate/4859634 is the private resource path of the API. This is the resource requested of the backend service.

This task assumes that you are already viewing the API Implementation tab for an API. To navigate to this tab, first select an API from the APIs list page, and then click the

API Implementation tab.

To configure the API Request URL:

Hover over API Request and then click Edit.

Description of the illustration api-request-edit.png

The Edit Policy dialog appears.
Provide the following information to configure the request:
1. (Optional) In the Your Policy Name field, enter a name for the policy.
2. (Optional) In the Comments field, describe why you are applying the policy for this API.
3. From the Protocol list, select the protocol over which the gateway receives requests for the API. Your options are HTTP, HTTPS, or HTTP & HTTPS.
4. In the API Endpoint URL field, enter the endpoint URL for this API. This is case sensitive; energy and Energy are considered different endpoints.
  
  The following endpoints are reserved for internal use: /apiplatform and /prm_pm_rest. Do not use these values as endpoints for your APIs.
5. Click Apply to save your changes and close the dialog, or click Apply as Draft to save a draft of your policy configuration.
Click Save.

The API Request URL is configured.

Important:

The API Implementation is not valid until you also configure the service request. You cannot deploy it to a gateway until you configure the service request.

The API Request URL is not displayed in the Developer Portal when the API is published. You must provide it in the documentation so Application Developers know where to send requests.

Configure the Service Request URL

The service request is the URL at which your backend service receives requests.

When a request meets all policy conditions, the gateway routes the request to this URL and calls your service. Note that the service request URL can point to any of your service’s resources, not just its base URL. This way you can restrict users to access only a subset of your API’s resources.

You can also control which requests are passed through by configuring the headers. By default, all headers are passed through except Proxy-Authorization, Authorization, Content-Length, Transfer-Encoding, Host, OSCGOAuthBearer. OSCGOAuthMAC, Anonymous, OSCGProxy-Authorization, OSCGSoapHeader, and OSCGAppKeyHeader.

REST and SOAP backend services are supported.

Some policies, such as OAuth 2.0, method mapping, and interface filtering, were designed to work primarily with REST services; it may not make sense to apply these policies to SOAP services.

This task assumes that you are already viewing the API Implementation tab for an API. To navigate to this tab, first select an API from the APIs list page, and then click the

API Implementation tab.

To configure the service request:

Hover over the Service Request region, and then click Edit.

Description of the illustration service-request-edit.png

The Edit Policy dialog appears.
From the Edit Policy dialog:
1. Expand the Configure Headers section.
2. In the all the Headers list, select Pass through or Drop.
3. If you selected Pass through, click the Drop Headers field to list header names to be deleted. Click in the field and select a header to drop. Repeat for each header you want to drop. You can also type the header name in the field and press Enter.
4. If you selected Drop, click the Pass Through Headers field to list header names to be passed through. Click in the field and select a header to be passed through. Repeat for each header you want to drop. You can also type the header name in the field.
5. To add or update headers, click the Header Name list and select the header you want to add or update, or type the header name and press Enter. Enter a value for the header in the Header Value field. .
6. (Optional) Click the + (Add new Header) icon to add more headers as needed. Repeat Step 2h for each header you add.
7. In the Service section, choose one of the following:
  - Select Existing: Click the Select Service button to select a service from the list of services available. You can only add services for which you are issued the Manage Service or Reference Service grant.
  - Enter a URL: Use this option to enter a URL for the service. With this option, you can also select the Use Gateway Node Proxy option if a proxy is required to call the service from the gateway node your API will be deployed to.
    
    Gateway Managers with the Manage Gateway grant can configure proxies for gateway nodes they manage. This allows for different proxy configurations for dev and production gateways or different proxies for nodes located in separate data centers. If this option is selected, but no proxy is configured for a node the API is deployed to, the request is passed from the gateway node to the backend service without using a proxy.
8. (Optional) Click the Select Service Account button and select the service account containing credentials required to access the service. Note that selecting a service account here overrides any service account attached to the service, if you selected one above.
  
  You can only add service accounts for which you are issued the Manage Service Account or Reference Service Account grant.
9. Click Apply to save your changes and close the dialog, or click Apply as Draft to save a draft of your policy configuration.
Click Save.

The service request URL is configured.

Important:

The API Implementation is not valid until you also configure the API request. You cannot deploy it to a gateway until you configure the API request.

Apply OAuth 2.0 Policies

Use an OAuth 2.0 policy to secure an API using OAuth 2.0.

A client application is authenticated by the identity provider and receives an access token. The client application sends the token with requests to the gateway, which acts as an OAuth enforcer and validates the token. If the token is valid, the request is passed on to the protected resource. If the token isn’t valid, the request is rejected.

In addition to validating tokens, you can limit access to your APIs by scope. You can also limit access per HTTP method (GET, PUT, POST, and DELETE) to specific scopes. For instance, you can allow only tokens issued for .WRITE scopes for POST operations.

This policy can be added only to the request flow.

This task assumes that you are already viewing the API Implementation tab for an API. To navigate to this tab, first select an API from the APIs list page, and then click the

API Implementation tab.

To configure an OAuth 2.0 policy:

In the Available Policies region, expand Security, hover over OAuth 2.0, and then click Apply.
The Apply Policy dialog appears.
From the Apply Policy dialog:
1. (Optional) In the Your Policy Name field, enter a name for the policy.
2. (Optional) In the Comments field, describe why you are applying the policy for this API.
3. From the Place after the following policy list, select the policy after which this policy is placed in the request flow.
4. Click Next.
5. From the Scope Enforcement Options section, select Any to allow all scopes (passing all requests with a valid token), select At Least One to pass requests containing at least one of the scopes you specify, or select HTTP Method Restricted to define which scopes are allowed to access resources based on HTTP method: GET, PUT, POST, and DELETE.
6. If you selected At Least One, enter a scope, like .READ, into the Valid Scope field, and then press the Enter key.
  
  You can enter multiple scopes. Requests (with valid tokens) from any scopes you enter in a single field are passed to the backend service. All other requests are rejected, even if the tokens are valid. Press Enter after entering each scope. Remove a scope by clicking the X next to it.
7. If you selected HTTP Method Restricted, select an HTTP method from the Method list, enter a scope, like .READ, into the Valid Scope field, and then press the Enter key.
  
  You can enter multiple scopes. The gateway validates that the scope claim (named “scope”) is present in the access token. Requests (with valid tokens) from any scopes you enter in a single field for an HTTP method are passed to the backend service. All other requests are rejected, even if the tokens are valid. Press Enter after entering each scope. Remove a scope by clicking the X next to it.
8. (Optional) Click the + (Add Scope) icon to add an additional scope enforcement condition. Repeat Step 2f if you selected At Least One or Step 2g if you selected HTTP Method Restricted to configure additional scope enforcement options.
9. Click Apply to save your changes and close the dialog, or click Apply as Draft to save a draft of your policy configuration.
Click Save.

The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

Apply Key Validation Policies

Use a key validation policy when you want to reject requests from unregistered (anonymous) applications.

Keys are distributed to clients when they register to use an API on the Developer Portal. At runtime, if they key is not present in the given header or query parameter, or if the application is not registered, the request is rejected; the client receives a 400 Bad Request error if no key validation header or query parameter is passed or a 403 Forbidden error if an invalid key is passed.

This policy can be added only to the request flow.

You can only apply the key validation policy once per API.

This task assumes that you are already viewing the API Implementation tab for an API. To navigate to this tab, first select an API from the APIs list page, and then click the

API Implementation tab.

To configure a key validation policy:

In the Available Policies region, expand Security, hover over Key Validation, and then click Apply.

If you have already applied a key validation policy to this API, the Apply button is disabled. You can only apply the key validation policy once per API.

The Apply Policy dialog appears.
From the Apply Policy dialog:
1. (Optional) In the Your Policy Name field, enter a name for the policy.
2. (Optional) In the Comments field, describe why you are applying the policy for this API.
3. From the Place after the following policy list, select the policy after which this policy is placed in the request flow.
4. Click Next.
5. From the Key Delivery Approach region, select Query Parameter if the client is to pass the key as a query parameter, or select Header if the client is to pass the key in a header.
6. In the Key Query Parameter or Key Header field, enter the name of the query parameter or header with which clients must pass the key. The request is rejected if the parameter/header is not present, if the key is not present, or if the key is invalid.
7. Click Apply to save your changes and close the dialog, or click Apply as Draft to save a draft of your policy configuration.
Click Save.

The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

Apply Basic Authentication Policies

Use a basic authentication policy to secure an API using the basic authentication protocol. The policy validates the value of the Authorization HTTP header against the identity store that the gateway node is configured against.

After successful authentication, the gateway executes the next policy in the flow or sends the request to the backend service. If authentication fails, the client receives a 401 Unauthorized error.

This policy is not compatible with any other authentication security policy (like OAuth 2.0); only one of these can be present in each API’s request flow.

This policy can be added only to the request flow.

This task assumes that you are already viewing the API Implementation tab for an API. To navigate to this tab, first select an API from the APIs list page, and then click the

API Implementation tab.

To apply a basic authentication policy:

In the Available Policies region, expand Security, hover over Basic Auth, and then click Apply.
The Apply Policy dialog appears.
From the Apply Policy dialog:
1. (Optional) In the Your Policy Name field, enter a name for the policy.
2. (Optional) In the Comments field, describe why you are applying the policy for this API.
3. From the Place after the following policy list, select the policy after which this policy is placed in the request flow.
4. Click Next.
5. From the Authenticated Users section, select Specific Users to pass requests from specific authenticated users or groups, or select All Users to pass requests from all authenticated users.
6. If you selected Specific Users, enter each user or you want to be able to call this API into the Account field, and then press the Enter key. Requests from all other users or groups are rejected.
  
  Click the + icon to add another row to enter user accounts into.
7. Click Apply to save your changes and close the dialog, or click Apply as Draft to save a draft of your policy configuration.
Click Save.

The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

Applying IP Filter Validation Policies

Use the IP Filter Validation policy to control which IP Addresses can successfully send requests to your API. IPv4 and IPv6 addresses are supported. The gateway receives the client’s address from the HttpRequest.

Note:

The IP filter Validation policy can’t be placed first in the request policy flow. Other security polices must be placed before it. If you want to filter out requests from potentially malicious sources before they can be rejected by the IP Filter Validation policy, use the load balancer provisioned with your service instance.

This policy can be added only to the request flow.

This task assumes that you are already viewing the API Implementation tab for an API. To navigate to this tab, first select an API from the APIs list page, and then click the

API Implementation tab.

To configure an IP filter validation policy:

In the Available Policies region, expand Security, hover over IP Filter Validation, and then click Apply.
The Apply Policy dialog appears.
From the Apply Policy dialog:
1. (Optional) In the Your Policy Name field, enter a name for the policy.
2. (Optional) In the Comments field, describe why you are applying the policy for this API.
3. From the Place after the following policy list, select the policy after which this policy is placed in the request flow.
4. Click Next.
5. From the IP Address Conditions list, select one of the following:
  - Select PASS to pass the request if any of the IP Address conditions are met.
  - Select REJECT to reject the request to the API if any of the IP Address conditions are met.
    
    Tip:
    
    The requester receives a 403 Forbidden HTTP status code and an “IP filter validation failed” message in response to a rejected request.
6. In the IP Address field, select either IPv4 or IPv6.
7. In the Expression field, select the expression used to evaluate the addresses entered into the Value field. The following expressions are available:
  - = (is equal to)
  - != (is not equal to)
  - Inside (is inside of specified range), like 12.12.1.100-12.12.12.122
  - Regex Match (is equal to an address included in the supplied regex mask. The Regex is made up of wildcard characters. If the IP of the host that is making the request to the API matches the wildcard, then it is passed or rejected. If no condition is evaluated to true, the opposite of the action gets executed.), like 12.12.1.*
  - CIDR Notation (is equal to an address included in the supplied CIDR notation expression), like 12.12.12.123/24, which includes 12.12.12.0-12.12.12.255
8. In the Value field, enter the IP Address value you want the expression to evaluate. The values you enter in this field differ based on the expression you chose in the previous step.
  
  For example, if you chose Inside, enter an IP address to begin and to end the range. If the IP address from which this request is sent is within this range, the request is either passed or rejected based on the behavior you specified.
  
  If the IP address is not within this range, each subsequent IP address condition is evaluated. When an IP address condition evaluates as true, the request is either passed or rejected based on the behavior you specified. If no condition is evaluated to true, the opposite of the action gets executed.
9. (Optional) Click the + (Add a new condition) icon to add additional conditions. Repeat Step 2e through Step 2g to populate the data for any additional conditions you add.
10. Click Apply to save your changes and close the dialog, or click Apply as Draft to save a draft of your policy configuration.
Click Save.

The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

Apply Outbound WSS Username Token Policies

Use an outbound WSS username token policy to enable an end-user identity to be passed over multiple hops before reaching the destination Web Service. The user identity is inserted into the message and is available for processing at each hop on its path.

The client application sends the requests to the API Gateway as a SOAP payload, but the credentials are encapsulated in a WS-Security wsse:UsernameToken element in the message header. While the REST2SOAP policy can create a SOAP call from a REST call, the generated SOAP payload does not include the wsse entry required by the service. This policy can be used in conjunction with the REST2SOAP policy.

The username and password credentials are stored in a WSS Username Token service account. You must create this service account before you can configure this policy. See Create a Service Account.

This policy can be added only to the request flow.

This task assumes that you are already viewing the API Implementation tab for an API. To navigate to this tab, first select an API from the APIs list page, and then click the

API Implementation tab.

To configure an outbound WSS username token policy:

In the Available Policies region, expand Security, hover over Outbound WSS Username Token, and then click Apply.
The Apply Policy dialog appears.
From the Apply Policy dialog:
1. (Optional) In the Your Policy Name field, enter a name for the policy.
2. (Optional) In the Comments field, describe why you are applying the policy for this API.
3. From the Place after the following policy list, select the policy after which this policy is placed in the request flow.
4. Click Next.
5. From the Select password transmission type list, Select Password Digest or Password Text.
6. Click Select Service Account, select a user account of the type WSSUsername and click Select.
7. Select Enable the mustUnderstand attribute if you want to require the receiver processing the header to recognize the wsse element.
8. Select Add timestamp to include the creation and expiration times of the message. You can set the expiration delay by defining a delay added to the creation time.
9. Click Apply to save your changes and close the dialog, or click Apply as Draft to save a draft of your policy configuration.
Click Save.

(Optional) Enter the result of the procedure here.

Apply CORS Policies

Use a CORS policy to specify which domains are allowed to send requests to your service.

By default, the gateway rejects requests from domains other than its own. Many use cases require that services are invoked from other domains. Requests can be sent with an Origin header that includes the requesting domain. When applied, the CORS policy reads the value in the Origin header and compares it to allowed domains you specify. If these match, the request is passed to the next policy or the backend service and this header is sent with the response:

Access-Control-Allow-Origin: *

You can configure the policy to allow requests from specific domains or from all domains.

Other CORS features are not supported in this release.

This policy can be added only to the request flow.

This task assumes that you are already viewing the API Implementation tab for an API. To navigate to this tab, first select an API from the APIs list page, and then click the

API Implementation tab.

To configure a CORS policy:

In the Available Policies region, expand Security, hover over CORS, and then click Apply.
The Apply Policy dialog appears.
From the Apply Policy dialog:
1. (Optional) In the Your Policy Name field, enter a name for the policy.
2. (Optional) In the Comments field, describe why you are applying the policy for this API.
3. From the Place after the following policy list, select the policy after which this policy is placed in the request flow.
4. Click Next.
5. To specify domains from which requests are allowed, ensure that Specific Domains is selected. Type the domains that you want to allow, and press Enter after each domain.
  Tip:
  
  Click the Add (+) icon to add a field. This way you can group similar domains in their own field.
  
  Requests from domains that you haven’t explicitly allowed receive this 403 Forbidden message in response:
```
Origin not allowed.
```
6. To allow requests from all domains, click All Domains.
7. Click Apply to save your changes and close the dialog, or click Apply as Draft to save a draft of your policy configuration.
Click Save.

The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

Apply Inbound WSS Username Token Policies

Use an inbound WSS username token policy to enforce verification of credentials sent within the SOAP payload and allow only authorized users to access APIs

The policy can be configured to allow authentication against all users or only specific ones. Weblogic DefaultAuthenticator is the default security provider, and users can be created through the WebLogic console.

The client application sends the requests to the API Gateway as a SOAP payload. The API Gateway must enforce access by checking if the credentials sent within the SOAP payload match with a valid user from the WLS Identity Store. Only the PasswordText option of PasswordType is supported, since it is not possible to retrieve the plain password from the SHA1 hashed digest value.

When an application makes a request to the API, the credentials are extracted from the SOAP payload. The security provider validates credentials and translates it into a security subject. If the user is not provided, or the credentials are invalid, the request results in an authorization failure.

Note:

This policy is not supported in GatewayLite.

This policy can be added only to the request flow.

This task assumes that you are already viewing the API Implementation tab for an API. To navigate to this tab, first select an API from the APIs list page, and then click the

API Implementation tab.

To configure an inbound WSS username token policy:

In the Available Policies region, expand Security, hover over Inbound WSS Username Token, and then click Apply.
The Apply Policy dialog appears.
From the Apply Policy dialog:
1. (Optional) In the Your Policy Name field, enter a name for the policy.
2. (Optional) In the Comments field, describe why you are applying the policy for this API.
3. From the Place after the following policy list, select the policy after which this policy is placed in the request flow.
4. Click Next.
5. In the Authenticated Users section, select All Users, or to indicate specific user accounts, select Specific Users. Click in the Account box and enter the names of user accounts or groups. Press Enter after each account. Click the + icon to add another row.
6. Select the Remove WSS header after authorization option, if desired.
7. Click Apply to save your changes and close the dialog, or click Apply as Draft to save a draft of your policy configuration.
Click Save.

The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

Apply API Throttling–Delay Policies

Use an API throttling-delay policy to control the global volume of requests to an API by delaying requests exceeding a threshold you set.

API Throttling prevents the abuse of an API. For example, if you want an API to accept only 50 requests per second, all requests received after the 50th during that second are delayed by the time you specify. Throttling is applied to all API requests, regardless of the source.

The limits that you set can be applied to the entire gateway or to each node within the gateway. For example, if you have a gateway with two nodes, and you set a limit for each API of 100 requests per minute, you can choose to apply the limit to each node in the gateway so that each node has 100 requests per minute. You can also apply the limit to the gateway, so that each node has 50 requests per minute.

This policy is different than the API rate limiting policy; requests exceeding the threshold set for that policy are rejected instead of delayed.

This policy can be added only to the request flow.

This task assumes that you are already viewing the API Implementation tab for an API. To navigate to this tab, first select an API from the APIs list page, and then click the

API Implementation tab.

To configure an API throttling-delay policy:

In the Available Policies region, expand Traffic Management, hover over API Throttling–Delay, and then click Apply.
The Apply Policy dialog appears.
From the Apply Policy dialog:
1. (Optional) In the Your Policy Name field, enter a name for the policy.
2. (Optional) In the Comments field, describe why you are applying the policy for this API.
3. From the Place after the following policy list, select the policy after which this policy is placed in the request flow.
4. Click Next.
5. In the Allow API Throttling field, select per Logical Gateway or per Node.
6. In the Condition 1 section, choose one of the following expressions to use to evaluate the condition: Greater than, Greater than or equal to, or Is between.
7. Enter a positive integer.
8. From the list, select the time period during which this condition applies. The following time periods are available:
  - Per second
  - Per minute
  - Per hour
  - Per day
  - Per week
  - Per month
  Requests meeting the conditions you specify are delayed. For example, if you specified Greater than, 50, and Per second, requests 1 to 50 in a given second are passed as usual. Requests 51+ are delayed by the time period you specify in the following steps.
9. In the Delay requests by field, enter a value to delay requests by. This value must be an integer.
10. From the list, select Milliseconds or Seconds.
  Requests meeting the policy conditions are delayed by this time period. For example, if you specified 5 Seconds, throttled requests are passed five seconds after each is received.
11. (Optional) Click the + (Add a new condition) icon to add additional conditions. Repeat Step 2e through Step 2i for each condition you add.
12. Click Apply to save your changes and close the dialog, or click Apply as Draft to save a draft of your policy configuration.
Click Save.

The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

Apply Application Rate Limiting Policies

Use an application rate limiting policy to limit the amount of requests an API allows from each application over time periods that you specify. This time period is defined in seconds, minutes, hours, days, weeks, or months.

The limits that you set can be applied to the entire gateway or to each node within the gateway. For example, if you have a gateway with two nodes, and you set a limit for each application of 100 requests per minute, you can choose to apply the limit to each node in the gateway so that each node has 100 requests per minute. You can also apply the limit to the gateway, so that each node has 50 requests per minute. Gateways reject requests from a given application exceeding any of the thresholds you set.

This policy is different than the API rate limit policy. This policy counts requests from each application separately toward each policy condition. The API rate limit policy counts all requests to an API, regardless of the requesting application, toward each policy condition.

This policy must be paired with a key validation policy. The gateway determines which application is sending a request by reading the app key sent with the request. Application rate limit policies have no effect if the API does not also have a key validation policy applied.

This policy can be added only to the request flow.

This task assumes that you are already viewing the API Implementation tab for an API. To navigate to this tab, first select an API from the APIs list page, and then click the

API Implementation tab.

To configure an application rate limiting policy:

In the Available Policies region, expand Traffic Management, hover over Application Rate Limiting, and then click Apply.
The Apply Policy dialog appears.
From the Apply Policy dialog:
1. (Optional) In the Your Policy Name field, enter a name for the policy.
2. (Optional) In the Comments field, describe why you are applying the policy for this API.
3. From the Place after the following policy list, select the policy after which this policy is placed in the request flow.
4. Click Next.
5. In the Allow Application Rate Limiting field, select per Logical Gateway or per Node.
6. In the Rate Limit Per Application field, enter a positive integer.
7. From the Time Interval field, select the time period during which this condition applies. The following time periods are available:
  - Second
  - Minute
  - Hour
  - Day
  - Week
  - Month
  For example, if you enter 100 and select Minute, the first one hundred requests received during a single minute from one application continue to the next policy or are routed to the backend service, depending on the API’s implementation. Any subsequent requests received from the same application during the same minute are rejected. Requests received from other applications are passed if the limit has not been reached for that application.
8. (Optional) Click the + (Add a new condition) icon to add additional conditions. Repeat Step 2d and Step 2e for each condition you add. Requests are rejected if at least one of the thresholds you set are exceeded. Requests are passed if none of the thresholds you set are exceeded.
9. Click Apply to save your changes and close the dialog, or click Apply as Draft to save a draft of your policy configuration.
Click Save.

The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

Apply API Rate Limiting Policies

Use an API rate limiting policy to limit the total number of requests an API allows over a time period that you specify. This time period is defined in seconds, minutes, hours, days, weeks, or months.

This policy is different than the application rate limit policy. This policy counts all requests to an API, regardless of the requesting application, toward each policy condition. The application rate limit policy counts requests from each application separately toward each policy condition.

This policy can be added only to the request flow.

This task assumes that you are already viewing the API Implementation tab for an API. To navigate to this tab, first select an API from the APIs list page, and then click the

API Implementation tab.

To configure an API rate limiting policy:

In the Available Policies region, expand Traffic Management, hover over API Rate Limiting, and then click Apply.
The Apply Policy dialog appears.
From the Apply Policy dialog:
1. (Optional) In the Your Policy Name field, enter a name for the policy.
2. (Optional) In the Comments field, describe why you are applying the policy for this API.
3. From the Place after the following policy list, select the policy after which this policy is placed in the request flow.
4. Click Next.
5. In the Allow API Rate Limiting field, select per Logical Gateway or per Node.
6. In the API Rate Limit field, enter a positive integer.
7. From the Time Interval list, select the time period during which this condition applies. The following time periods are available:
  - Second
  - Minute
  - Hour
  - Day
  - Week
  - Month
  For example, if you enter 100 and select Minute, the first one hundred requests received during a single minute continue to the next policy or are routed to the backend service, depending on the API’s configuration. Any subsequent requests received during the same minute are rejected.
8. (Optional) Click the + (Add a new condition) icon to add additional conditions. Repeat Step 2e and Step 2f for each condition you add. Requests are rejected if at least one of the thresholds you set are exceeded. Requests are passed if none of the thresholds you set are exceeded.
9. Click Apply to save your changes and close the dialog, or click Apply as Draft to save a draft of your policy configuration.
Click Save.

The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

Apply Header Field Filtering Policies

Use the header field filtering policy to filter the request headers for length and format. It can be used for security or to reduce the occurrences of failures or errors at the service layer. For example, an API Manager would use this to stop excessively large headers in requests to prevent inadvertent or malicious attacks to a service.

Requests are rejected when selected header values are too large. Once a condition is violated, processing stops. Duplicate conditions are not allowed.

The value in the Value is longer than field must be an integer. Only bytes and kilobytes are units of size.

This task assumes that you are already viewing the API Implementation tab for an API. To navigate to this tab, first select an API from the APIs list page, and then click the

API Implementation tab.

This policy can be added only to the request flow.

To configure a header field filtering policy:

In the Available Policies region, expand Interface Management, hover over Header Field Filtering, and then click Apply.
The Apply Policy dialog appears.
From the Apply Policy dialog:
1. (Optional) In the Your Policy Name field, enter a name for the policy.
2. (Optional) In the Comments field, describe why you are applying the policy for this API.
3. From the Place after the following policy list, select the policy after which this policy is placed in the request flow.
4. In the Resources field, enter the resources you want to use as conditions, and then press Enter. You can enter as many resources as you like.
  
  Wildcards in resource paths are supported. For example, when entering /animals/* as the resource condition, requests to /animals/cats and /animals/dogs meet the specified resource condition.
5. In the Methods field, select the methods to filter by. Select ANY to filter by resource only.
6. In the Header Names field, enter the desired headers. Press Enter after each header name.
7. In the Value is longer than field, enter an integer. In the units list, select Bytes or Kilobytes.
8. (Optional) Click the + (Add a new header condition) icon to add additional header conditions. Repeat step 2f and step 2g for each header condition you add.
9. (Optional) Click the + (Add a new condition) icon to add additional conditions. Repeat step 2d through step 2g for each resource and method combination you add.
10. Click Apply to save your changes and close the dialog, or click Apply as Draft to save a draft of your policy configuration.
Click Save.

The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

Apply Interface Filtering Policies

Use an interface filtering policy to filter requests based on the resources and methods specified in the request.

This policy can be added only to the request flow.

This task assumes that you are already viewing the API Implementation tab for an API. To navigate to this tab, first select an API from the APIs list page, and then click the

API Implementation tab.

To configure an interface filtering policy:

In the Available Policies region, expand Interface Management, hover over Interface Filtering, and then click Apply.
The Apply Policy dialog appears.
From the Apply Policy dialog:
1. (Optional) In the Your Policy Name field, enter a name for the policy.
2. (Optional) In the Comments field, describe why you are applying the policy for this API.
3. From the Place after the following policy list, select the policy after which this policy is placed in the request flow.
4. Click Next.
5. From the list, select Pass to pass, or select Reject to reject, requests containing the resource and method combinations specified in the policy. Pass is the default option.
6. In the Resources field, enter the resources you want to use as conditions, and then press Enter You can enter as many resources as you like.
  
  Wildcards in resource paths are supported. For example, when entering /animals/* as the resource condition, requests to /animals/cats and /animals/dogs meet the specified resource condition.
7. In the Methods field, select the methods to filter by. Select ALL to filter by resource only.
  If the API was created with an Apiary specification, you have the option of configuring the resources using actions from the API specification or configuring them manually. If the API has an Apiary specification, the From API Spec option is selected automatically. If you want to configure the resources and methods manually, click the Manual option to display the Resources and Methods fields and continue as above. If you choose to use the API specification, click the Select Actions button to display the Select Actions from API Specifications dialog. Select the desired method and resource combinations from the list, or use the Select All option at the top of the list. Click Select to select the actions and return to the Apply Policy dialog.
8. (Optional) Click the + (Add a new condition) icon to add additional conditions. Repeat Step 2f and Step 2g for each resource and method combination you add.
9. Click Apply to save your changes and close the dialog, or click Apply as Draft to save a draft of your policy configuration.
Click Save.

The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

Apply Redaction Policies

Use a redaction policy to limit or remove certain fields and headers that appear in the request or response payload. In the request flow, you can control the header, queries, and payload contents before the backend service is invoked. In the response flow, you can control the response headers, queries, and payload content sent to the client.

This policy can be added to the request or response flows.

This task assumes that you are already viewing the API Implementation tab for an API. To navigate to this tab, first select an API from the APIs list page, and then click the

API Implementation tab.

To configure a field redaction policy:

In the Available Policies region, expand Interface Management, hover over Redaction, and then click Apply.
The Apply Policy dialog appears.
From the Apply Policy dialog:
1. (Optional) In the Your Policy Name field, enter a name for the policy.
2. (Optional) In the Comments field, describe why you are applying the policy for this API.
3. From the Place after the following policy list, select the policy after which this policy is placed in the request or response flow.
4. Click Next.
5. From the Redaction Conditions list, select Include Only to include only the specified headers or fields in the response, or select Exclude to exclude the specified headers or fields from the response.
  You can either include or exclude the whole fields. You cannot include specific values in the fields or exclude specific values from the fields.
6. (Optional) Click the + (Add a new condition) icon to add additional conditions. Repeat Step 2e for each condition you add.
7. Click Apply to save your changes and close the dialog, or click Apply as Draft to save a draft of your policy configuration.
Click Save.

The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

Example 4-1 Examples

For the following examples:

An exclude operation means that the referenced nodes and all of their children get deleted. If there is no match, the payload remains intact.
An include only operation means that only the referenced nodes and their children are kept. If there is no match, the payload is emptied.

JsonObject processing example

Input body

{
 "a": {
    "b": [ 1, 2, 3 ],
    "c": {
      "d": true
    },
    "e": [
      {
        "f": {
          "g": "11"
        },
        "h": [
          {
            "i": null,
            "j": 2
          }
        ],
        "g": "22"
      },
      {
        "f": 12,
        "h": ["j", "13"]
      },
      {},
      {
        "h": { "j" : "33"}
      }
    ]
  }
}

Rule Referenced fragments Result

Rule	Referenced fragments	Result
operation: exclude condition: a.c	`"c": { "d": true }`	`{ "a": { "b": [ 1, 2, 3 ], "e": [ { "f": { "g": "11" }, "h": [ { "i": null, "j": 2 } ], "g": "22" }, { "f": 12, "h": ["j", "13"] }, {}, { "h": { "j" : "33"} } ] } }`
operation: include only condition: a.x	references nothing	`{ }`

operation: exclude

condition: a.c

 "c": {
      "d": true
    }

{
  "a": {
    "b": [ 1, 2, 3 ],
    "e": [
      {
        "f": {
          "g": "11"
        },
        "h": [
          {
            "i": null,
            "j": 2
          }
        ],
        "g": "22"
      },
      {
        "f": 12,
        "h": ["j", "13"]
      },
      {},
      {
        "h": { "j" : "33"}
      }
    ]
  }
}

operation: include only

condition: a.x

references nothing

{
}

JSONArray processing example

Input body

[
 {
    "a": 0
 },
 {
    "b": [ 1, 2, 3 ],
    "c": {
      "d": true
     }
 },
 {},
 {
    "e": [
      {
        "f": {
          "g": "11"
        },
        "h": [
          {
            "i": null,
            "j": 2
          }
        ],
        "g": "22"
      },
      {
        "f": 12,
        "h": ["j", "13"]
      },
      {
        "h": { "j" : "33"}
      }
    ]
 }
]

Rule Referenced fragments Result

Rule	Referenced fragments	Result
operation: include only condition: [1].c.d Note: The array item count will be changed in this case.	`"c": { "d": true }`	`[ { "c": { "d": true } } ]`

operation: include only

condition: [1].c.d

Note:

The array item count will be changed in this case.

 "c": {
      "d": true
    }

[
  {
      "c": {
      "d": true
     }
   }
]

XML Processing example

Input body

<?xml version="1.0" encoding="UTF-8"?>
   <a>
      <b>
         <element>1</element>
         <element>2</element>
         <element>3</element>
      </b>
      <c>
        <d>true</d>
      </c>
      <e>
         <element>
            <f>
              <g>11</g>
            </f>
            <g>22</g>
            <h>
              <element>
                 <i>null</i>
                 <j>2</j>
              </element>
            </h>
        </element>
        <element/>
        <element>
            <f>12</f>
            <h>
               <element>j</element>
               <element>33</element>
            </h>
        </element>
        <element>
            <h>
               <j>33</j>
            </h>
        </element>
      </e>
   </a>

Rule Referenced fragments Result

Rule	Referenced fragments	Result
operation: include only condition: root.a.e.element[0].f	`<f> <g>11</g> </f>`	`<?xml version="1.0" encoding="UTF-8"?> <root> <a> <e> <element> <f> <g>11</g> </f> </element> </e> </a> </root>`

operation: include only

condition: root.a.e.element[0].f

<f>
   <g>11</g>
</f>

<?xml version="1.0" encoding="UTF-8"?>
<root>
   <a>
      <e>
         <element>
           <f>
              <g>11</g>
           </f>
         </element>
       </e>
   </a>
</root>

XML (with namespaces) Processing example

Input body

<list:employeeList xmlns:list="urn:corp:list" xmlns:emp="urn:corp:emp"
      xmlns:sec="urn:corp:sec>
  <list:personList>
    <emp:empID>E0000001</emp:empID>
    <sec:name>Sales</sec:name>
    <emp:name>John Smith</emp:name>
  </list:personList>
  <list:personList>
    <emp:empID>E0000002</emp:empID>
    <sec:name>Development</sec:name>
    <emp:name>Ichiro Tanaka</emp:name>
  </list:personList>
  <list:personList>
    <emp:empID>E0000003</emp:empID>
    <sec:name>Development</sec:name>
    <emp:name>Jiro Suzuki</emp:name>
  </list:personList>
  <list:personList>
    <emp:empID>E0000004</emp:empID>
    <sec:name>Administrative</sec:name>
    <emp:name>Saburo Takahashi</emp:name>
  </list:personList>
</list:employeeList>

Rule Referenced fragments Result

Rule	Referenced fragments	Result
operation: include only condition: employeeList.personList[1].name Note: condition: path expression without any namespace processing: namespaces are ignored	All the <name> nodes (under personList[1]) regardless of the namespace	`<list:employeeList xmlns:list="urn:corp:list" xmlns:emp="urn:corp:emp" xmlns:sec="urn:corp:sec"> <list:personList> <sec:name>Development</sec:name> <emp:name>Ichiro Tanaka</emp:name> </list:personList> </list:employeeList>`

operation: include only

condition: employeeList.personList[1].name

Note:

condition: path expression without any namespace

processing: namespaces are ignored

All the <name> nodes (under personList[1]) regardless of the namespace

<list:employeeList 
      xmlns:list="urn:corp:list" 
      xmlns:emp="urn:corp:emp" 
      xmlns:sec="urn:corp:sec">
  <list:personList>
    <sec:name>Development</sec:name>
    <emp:name>Ichiro Tanaka</emp:name>
  </list:personList>
</list:employeeList>

Apply Header Validation Policies

Use a header validation policy when you want to pass or reject requests based on the presence of or value of headers sent with the request.

This policy can be added only to the request flow.

This task assumes that you are already viewing the API Implementation tab for an API. To navigate to this tab, first select an API from the APIs list page, and then click the

API Implementation tab.

To configure a header validation policy:

In the Available Policies region, expand Interface Management, hover over Header Validation, and then click Apply.
The Apply Policy dialog appears.
From the Apply Policy dialog:
1. (Optional) In the Your Policy Name field, enter a name for the policy.
2. (Optional) In the Comments field, describe why you are applying the policy for this API.
3. From the Place after the following policy list, select the policy after which this policy is placed in the request flow.
4. Click Next.
5. Select Pass to pass requests meeting the policy criteria, or select Reject to reject requests meeting the criteria. Reject is the default option.
  
  Tip:
  
  The client receives a 400 Bad request HTTP status code and a “Bad request” message in response to a rejected request.
  
  When validations fail, you can view the details at apics/analytics/logs.
6. Select Any to pass or reject a request if any of the header conditions you specify evaluate as true. Select All to pass or reject a request only if all of the header conditions you specify evaluate as true.
7. Enter a header name into the Name field.
8. Choose an expression with which to evaluate the header in the Operator field. The following expressions are available:
  - = (is equal to)
  - != (is not equal to)
  - > (is greater than)
  - < (is less than)
  - >= (is greater than or equal to)
  - <= (is less than or equal to)
  - Is Null (the header has no value)
  - Is Not Null (the header is present and has a value)
9. Depending on the expression you selected, enter a relevant value into the Value field. Wild cards are not supported. Some expressions, like Is Null and Is Not Null, do not require values.
  
  If this header is not present, or has a value other than the one provided, each subsequent header condition is evaluated if you chose Any; if you chose All the request is passed or rejected based on the behavior you selected. If the next header evaluates as true, the request is passed or rejected based on the behavior you selected. If you chose All, the request is passed or rejected as you chose only if all conditions are met. If there are duplicate headers, the first condition is validated and then the duplicate condition is validated, even if they are conflicting.
10. (Optional) Click the + (Add a new condition) icon to add additional conditions. Repeat Step 2f through Step 2i to populate the data for any additional conditions you add.
11. Click Apply to save your changes and close the dialog, or click Apply as Draft to save a draft of your policy configuration.
Click Save.

The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

Apply Request Payload Validation Policies

Use the Request Payload Validation policy to validate the request message body for length and format. It can also be used for security or to reduce the occurrence of failures or errors at the service ayer.

Validation aspects to consider for this policy:

Duplicate conditions are not allowed. Duplication is based on the combination of Resource and Method fields.
The value in the Reject if Message Body exceeds should be an integer.
For the Unit field, only bytes, kilobytes, and megabytes are expected.
The Select Content-Types field is active only if the doesn’t match the content for option is selected. It can only have the following content types:
- application/json
- application/xml
- application/x-www-form-urlencoded
- multipart/form-data

This policy can be added only to the request flow.

This task assumes that you are already viewing the API Implementation tab for an API. To navigate to this tab, first select an API from the APIs list page, and then click the

API Implementation tab.

To configure a request payload validation policy:

In the Available Policies region, expand Interface Management, hover over Request Payload Validation, and then click Apply.
The Apply Policy dialog appears.
From the Apply Policy dialog:
1. (Optional) In the Your Policy Name field, enter a name for the policy.
2. (Optional) In the Comments field, describe why you are applying the policy for this API.
3. From the Place after the following policy list, select the policy after which this policy is placed in the request flow.
4. Click Next.
5. In the Resources field, type the resource path(s) (like /estimate, including the slash) that you want to route to a different service request URL, and then press Enter.
  
  You can enter multiple resource paths. Press Enter after entering each resource path. Remove a path by clicking the X next to it.
6. In the Methods field, select the methods to filter by. Select Any to filter by resource only.
7. In the Reject if Message Body exceeds field, enter an integer. In the Unit field, select the desired unit.
8. In the Reject if Content-Type Header area, select either the is not present option or the doesn’t match the content for option. If you select the second option, click in the Select Content-Types field and select the desired content type.
9. (Optional) Click the + (Add a new condition) icon to add additional conditions. Repeat Steps 2e through Step 2h for each resource and method combination you add.
10. Click Apply to save your changes and close the dialog, or click Apply as Draft to save a draft of your policy configuration.
Click Save.

The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

Apply Method Mapping Policies

Use the method mapping policy to change the HTTP method of a request to another method you specify before passing it to the service.

In addition to methods, this policy can also map resources, query parameters, headers, and fields from one value to another that you configure before the request is passed to the service.

This is a transformation policy. It attempts to make changes, but it does not block the request if it cannot perform the transformation. It is meant to be used in conjunction with a validation policy so that unintended requests have already been filtered out by the time this policy is applied.

The Apply Policy dialog for the method mapping policy has two columns: one labeled API and another labeled Service. When a request is received that meets conditions set in the API column, matching fields are replaced with data in the Service column when the request is sent to the backend service. For example, if a request is sent with a GET method, but you want to replace it with a POST method in the call to the service, you configure a method mapping policy to change the method from GET to POST.

This policy can be added only to the request flow.

This task assumes that you are already viewing the API Implementation tab for an API. To navigate to this tab, first select an API from the APIs list page, and then click the

API Implementation tab.

To configure a method mapping policy:

In the Available Policies region, expand Interface Management, hover over Method Mapping, and then click Apply.
The Apply Policy dialog appears.
From the Apply Policy dialog:
1. (Optional) In the Your Policy Name field, enter a name for the policy.
2. (Optional) In the Comments field, describe why you are applying the policy for this API.
3. From the Place after the following policy list, select the policy after which this policy is placed in the request flow.
4. Click Next.
5. In the Resources(s) field in the API section, select the resources(s) to change.
  If the API was created with an Apiary specification, you have the option of configuring the resources using actions from the API specification or configuring them manually. If the API has an Apiary specification, the From API Spec option is selected automatically. If you want to configure the resources and methods manually, click the Manual option to display the Resources and Methods fields in the API and Service sections and continue as below. If you choose to use the API specification, click the Select Actions button in the API section to display the Select Actions from API Specifications dialog. Select the desired method and resource combinations from the list, or use the Select All option at the top of the list. Click Select to select the actions and return to the Apply Policy dialog. Click the Select Action in the Service section to select the resource and methods to request from the service in a similar manner.
6. In the Methods field in the API section, select the methods to change.
7. In the Resource field in the Service section, select the resource to request from the service.
8. In the Method field in the Service section, select the method to send requests with to the service. Select Keep Same to retain the value selected in the API section.
9. (Optional) To map query parameters, expand the Query Parameters heading and click the Add a new query parameter button (+). In the API column, enter the query parameter you want to change. In the Service column, enter the query parameter you want to replace its paired API query parameter with and send to the service.
10. (Optional) To map headers, expand the Headers heading and click the Add a new header button (+). In the API column, enter the header you want to change. In the Service column, enter the header you want to replace its paired API header with and send to the service.
11. (Optional) To map fields, expand the Fields heading and click the Add a new field button (+). In the API column, enter the field you want to change. In the Service column, enter the field you want to replace its paired API field with and send to the service.
12. (Optional) Click the + (Add a new condition) icon to add additional conditions.
13. Click Apply to save your changes and close the dialog, or click Apply as Draft to save a draft of your policy configuration.
Click Save.

The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

Method Mapping Use Cases

These use cases can serve as examples for using the method mapping policy.

Resource Mapping

If the incoming request resource matches any of the configured API side resources, then it is mapped to the service side resource. You can configure more than one resource on the API side, but it all maps to a single service side resource. For example, if the URL is http://myserver.com:8001/methodmap/1/business/resource/one/, the base URL is http://myserver.com:8001/methodmap/1/ and the resources are business/resource/one/. Anything after business is considered a resource.

API	Service
/dogs /cats	/animals

In the Resources section, you enter multiple resources in the API column on the left and a single resource in the Service column on the right. In the example table above, if you want dogs and cats to be transformed into animals, enter /dogs /cats in the left column and /animals on the right.

Method Mapping

Method mapping can be configured to map multiple API methods to a single service method; for example, GET, PUT, and POST should all map to POST in the service. There are other options, such as ANY in the API column on the left and KEEP SAME in the Service column on the right.

API	Service
ANY	POST
POST,PUT	KEEP SAME
ANY	KEEP SAME

In the example table above, if the API side is configured as ANY, then any request method maps to the configured Service method. If the API side is configured as POST,PUT and Service side is configured KEEP SAME, then the mappings apply to POST and PUT controls only.

Mappings

These mappings are applied only if all mapping conditions are met. Otherwise, the next condition is evaluated.

Header Mapping

Add Header with Static value : The incoming request does not have a header, and you want to add a static header such as xyz=123 to the incoming request header. The API column should be blank, and the Service column should have xyz=123.

API	Service
—	`xyz=123`

Add Header with Dynamic Value: The incoming request does not have a header, and you want to add a dynamic header with an xyz value to the incoming request header. The API column should be blank, and the Service column should have a statement that takes the value of a specific field from the payload and adds it to the xyz header. You can also use queries to set the value of the header. See the table below for examples.

API	Service
—	`xyz=${payload.fields.field1}`
—	`fromQuery=${queries.additional}`
—	`fromPayload=${payload.conditions[1].headerValue}`

Replace Header Name: The incoming request has a header, and you want to replace the header with another name and also remove the header from the original request. For example, you want to replace the header x-header-xyz with the header xyz. The API column should have the header to be replaced, and the Service column should have the replacement value for the header. If the header in the request is not x-header-xyz, then the original header is not replaced or removed.

API	Service
`x-header-xyz`	`xyz`
`acno`	`AccountNo`
`apiid=123`	`xyz.application.id=123`
`dept`	`department=${payload.conditions[0].headerName}`

Remove Header Name: The incoming request has a header, and you want to remove the header from the original request. For example, you want to remove the header with the name xyz from the request. The API column should have the name of the header, and the Service column should be blank.

API	Service
`xyz`	—
`xyz=123`	—

Query Parameter Mapping

Add Query with Static Value: The incoming request does not have a query, and you want to add a query such as xyz=123 to the incoming request. The API column should be blank and the Service column should have xyz=123.

API	Service
—	`xyz=123`

Add Query with Dynamic Value: The incoming request does not have a query, and you want to add a dynamic query with an xyz value to the incoming request header. The API column should be blank, and the Service column should have a statement that takes the value of a specific field from the payload and adds it to the xyz query. You can also use headers to set the value of the query. See the table below for examples.

API	Service
—	`xyz=${payload.fields.field1}`
—	`fromHeader=${headers.additional}`
—	`fromPayload=${payload.conditions[1].headerValue}`

Replace Query Name: The incoming request has a query, and you want to replace the query parameter with another name and also remove the query parameter from the original request. For example, you want to replace the query parameter dept with the parameter department. The API column should have the parameter to be replaced, and the Service column should have the replacement value for the parameter. If the query in the request is not dept, then the original query parameter is not replaced or removed. If there is a key value pair for example key=value in the API column, if the incoming request query parameter and its value match then only the query parameter is replaced or renamed.

API	Service
`dept`	`department`
`acno`	`AccountNo`
`dept=123`	`department=sales123`
`dept`	`department=${payload.conditions[0].headerName}`

Remove Query Parameter: The incoming request has a query parameter, and you want to remove the query parameter from the original request. For example, you want to remove the parameter with the name xyz from the request. The API column should have the name of the query parameter, and the Service column should be blank.

API	Service
`xyz`	—
`xyz=123`	—

Field Mapping

Fields are payload elements. This method allows you to modify the payload fields.

Replace Field Value: You can replace the field value by entering the field and its value in the API column and field and its value to be replaced in the Service column.

API	Service
`defaultCondition.routeToUrl=replace`	`defaultCondition.routeToUrl=http://myserver/sales/`
`Conditions[0].headerName=xyz`	`Conditions[0].headerName=aabbcc`

Replace Field Name: You can replace the field name by entering field name in the API column and the field name to be replaced in the Service column.

API	Service
`conditions[1].headerName`	`conditions[1].departmentName`
`defaultCondition.routeToUrl`	`defaultCondition.renameUrl`

Remove Field: You can remove a particular field from the incoming request payload by entering field path in the API column and leaving the Service column blank.

API	Service
`conditions[1].headerName`	—
`defaultCondition.routeToUrl`	—

Add a Field: You can add a particular field to the incoming request payload by leaving the API column blank and entering the path of the field and its value in the Service column.

API	Service
—	`defaultCondition.saleArea=APAC`
—	`conditions[1].headerName=xyzcompany`

Add a Dynamic Field or Value: You can add a particular field to the incoming request payload by leaving the API column blank and entering the path of the field and its value in the Service column. You can also assign the header or query parameter value to the field.

API	Service
—	`defaultCondition.saleArea=${payload.field1.fieldvalue}`
—	`conditions[1].headerName=${headers.abcd}`

Apply REST to SOAP Policies

Use the REST to SOAP to expose a SOAP service as a JSON REST service.

You can configure the REST to SOAP policy in one dialog box for both the request and the response pipeline.

The default configuration for the service is pre-populated from the WSDL file in a SOAP service. You can modify the REST to SOAP policy configuration for the request and the response. For the request, you can use dynamic path parameters to map resources to WSDL operations. THe SOAP payload can also be configured with dynamic values based on the REST request. For the response, the REST payload can be configured with dynamic values based on the SOAP response.

At runtime, the request part of the REST to SOAP policy is responsible for constructing the SOAP payload based on the JSON input. The response part of the policy is responsible for constructing the JSON response based on the SOAP output. All this is done without loading the provided WSDL/XSDs. Note that only JSON payloads are supported. For SOAP faults, either system faults or business faults, the content is converted to JSON and sent to the REST caller.

Before you apply the REST to SOAP policy, you must create a SOAP service and upload a WSDL file. See Creating a Service for more information.

The policy configuration saved as part of the API does not include the content of the WSDL/XSDs.

This task assumes that you are already viewing the API Implementation tab for an API. To navigate to this tab, first select an API from the APIs list page, and then click the

API Implementation tab.

To configure a REST to SOAP policy:

In the Available Policies region, expand Interface Management, hover over REST to SOAP, and then click Apply.
The Apply Policy dialog appears.
From the Apply Policy dialog:
1. (Optional) In the Your Policy Name field, enter a name for the policy.
2. (Optional) In the Comments field, describe why you are applying the policy for this API.
3. From the Place after the following policy list, select the policy after which this policy is placed in the request flow.
4. If you are editing the policy from the request flow, then from the Place after the following policy in response pipeline list, select the policy after which this policy is placed in the response flow. If you are editing the policy from the response flow, then from the Place after the following in response pipeline list, select the policy after which this policy is placed in the request flow.
5. Click Next.
In the Conversion Configuration section, click Select Service.
Click an existing SOAP service with WSDL and click Select.
All of the possible operations in the selected service are listed.
Click the box on the left of the row to select an operation. Enter the resource path without a slash in the Path field. You do not need to select all the operations listed before applying the policy. When you edit the policy later, you are presented again with all the operations in the WSDL with the already selected operations pre-selected. If the WSDL was updated, the policy dialog box notifies you about the update and give you the option to synchronize the list by clicking a Refresh button.
Click the down arrow on the right of the row to see a box in which you can view the REST to SOAP payload and the SOAP to REST payload.
Click Apply to save your changes and close the dialog, or click Apply as Draft to save a draft of your policy configuration. See Working with Draft Policies.
When you click Apply, the Service Request policy is updated to be automatically configured with the REST to SOAP service selected above. Click Ok in the banner.
If the Service Request policy was already configured with either a service or a URL, the service policy is not updated. You should open the Service Request and choose the REST to SOAP service. Otherwise, you may receive an invalid API request message when the policy is invoked. If the Service Request policy was not yet configured, the REST to SOAP service is added automatically.

Apply Header-Based Routing Policies

Use the header-based routing policy to route incoming requests to a specific service request URL based on the presence or value of a specified header. For example, you can specify a different backend service to route requests to different credit rating agencies based on the value of a header you specify.

This policy can be added only to the request flow.

This task assumes that you are already viewing the API Implementation tab for an API. To navigate to this tab, first select an API from the APIs list page, and then click the

API Implementation tab.

To configure a header-based routing policy:

In the Available Policies region, expand Routing, hover over Header Based Routing, and then click Apply.
The Edit Policy dialog appears.
From the Apply Policy dialog:
1. (Optional) In the Your Policy Name field, enter a name for the policy.
2. (Optional) In the Comments field, describe why you are applying the policy for this API.
3. From the Place after the following policy list, select the policy after which this policy is placed in the request flow.
4. Click Next.
5. Enter a header name into the Header field.
6. Choose an expression with which to evaluate the header. The following expressions are available:
  - = (is equal to)
  - != (is not equal to)
  - > (is greater than)
  - < (is less than)
  - >= (is greater than or equal to)
  - <= (is less than or equal to)
  - Is NULL (the header is not present or has no value)
  - Is NOT NULL (the header is present and has a value)
7. Depending on the expression you selected, enter a relevant value into the Value field. Some expressions, like IS NULL and IS NOT NULL, do not require values.
8. (Optional) To drop or add/update headers, expand the Configure Headers section.
  - To drop headers, click the Drop Headers field to list header names to be deleted for this condition. Click in the field and select a header to drop. Repeat for each header you want to drop. You can also type the header name in the field and press Enter.
  - To add or update headers, click the Header Name list and select the header you want to add or update, or type the header name and press Enter. Enter a value for the header in the Header Value field. Click the + (Add new Header) icon to add more headers as needed, specifying the header name and value for each one you add.
9. In the Service section, choose one of the following:
  - Select Existing: Click the Select Service button to select a service from the list of services available. You can only add services for which you are issued the Manage Service or Reference Service grant.
  - Enter a URL: Use this option to enter a URL for the service. With this option, you can also select the Use Gateway Node Proxy option if a proxy is required to call the service from the gateway node your API will be deployed to.
    
    Gateway Managers with the Manage Gateway grant can configure proxies for gateway nodes they manage. This allows for different proxy configurations for dev and production gateways or different proxies for nodes located in separate data centers. If this option is selected, but no proxy is configured for a node the API is deployed to, the request is passed from the gateway node to the backend service without using a proxy.
10. (Optional) Click the Select Service Account button and select the service account containing credentials required to access the service. Note that selecting a service account here overrides any service account attached to the service, if you selected one above.
  
  You can only add service accounts for which you are issued the Manage Service Account or Reference Service Account grant.
11. (Optional) Click the + (Add a new condition) icon to add additional conditions. Repeat Step 2f through Step 2j to populate the data for any additional conditions you add.
12. In the Otherwise section, choose one of the following behaviors to route all requests not matching the conditions you specified above:
  - (Default) Select Keep Default Service Request URL to route requests to the API’s default service request URL.
  - Select Configure Service Request to route requests to a specific service request. Configure headers, a service, and a service account as in the steps above.
13. Click Apply to save your changes and close the dialog, or click Apply as Draft to save a draft of your policy configuration.
Click Save.

The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

Apply Application-Based Routing Policies

Use an application-based routing policy to route requests from specific applications or application types to a service request URL that you specify.

The application-based routing policy must be used in tandem with a key validation policy.

This policy can be added only to the request flow.

This task assumes that you are already viewing the API Implementation tab for an API. To navigate to this tab, first select an API from the APIs list page, and then click the

API Implementation tab.

To configure an application-based routing policy:

In the Available Policies region, expand Routing, hover over Application-Based Routing, and then click Apply.
The Edit Policy dialog appears.
From the Apply Policy dialog:
1. (Optional) In the Your Policy Name field, enter a name for the policy.
2. (Optional) In the Comments field, describe why you are applying the policy for this API.
3. From the Place after the following policy list, select a key validation policy.
4. Click Next.
5. Click Select Applications >. Select one or more applications. Click the down arrow at the right of an application to view its description. If the list of applications is long, you can use the search box at the top of the list to search for it by name. Click Select to return to the Apply Policy dialog.
  
  If you enter multiple applications, requests from all applications in a single field are routed to the same Service URL.
6. (Optional) To drop or add/update headers, expand the Configure Headers section.
  - To drop headers, click the Drop Headers field to list header names to be deleted for this condition. Click in the field and select a header to drop. Repeat for each header you want to drop. You can also type the header name in the field and press Enter.
  - To add or update headers, click the Header Name list and select the header you want to add or update, or type the header name and press Enter. Enter a value for the header in the Header Value field. Click the + (Add new Header) icon to add more headers as needed, specifying the header name and value for each one you add.
7. In the Service section, choose one of the following:
  - Select Existing: Click the Select Service button to select a service from the list of services available. You can only add services for which you are issued the Manage Service or Reference Service grant.
  - Enter a URL: Use this option to enter a URL for the service. With this option, you can also select the Use Gateway Node Proxy option if a proxy is required to call the service from the gateway node your API will be deployed to.
    
    Gateway Managers with the Manage Gateway grant can configure proxies for gateway nodes they manage. This allows for different proxy configurations for dev and production gateways or different proxies for nodes located in separate data centers. If this option is selected, but no proxy is configured for a node the API is deployed to, the request is passed from the gateway node to the backend service without using a proxy.
8. (Optional) Click the Select Service Account button and select the service account containing credentials required to access the service. Note that selecting a service account here overrides any service account attached to the service, if you selected one above.
  
  You can only add service accounts for which you are issued the Manage Service Account or Reference Service Account grant.
9. (Optional) Click the + (Add a new condition) icon to add additional application routing conditions. Repeat steps 2e through 2h to populate the data for any additional conditions you add.
10. In the Otherwise section, choose one of the following behaviors to route all requests not matching the conditions you specified above:
  - (Default) Select Keep Default Service Request URL to route requests to the API’s default service request URL.
  - Select Configure Service Request to route requests to a specific service request. Configure headers, a service, and a service account as in the steps above.
11. Click Apply to save your changes and close the dialog, or click Apply as Draft to save a draft of your policy configuration.
Click Save.

The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

Apply Gateway-Based Routing Policies

Use a gateway-based routing policy to route requests to different service request URLs based on the gateway to which the API is deployed.

This policy can be added only to the request flow.

This task assumes that you are already viewing the API Implementation tab for an API. To navigate to this tab, first select an API from the APIs list page, and then click the

API Implementation tab.

To configure a gateway-based routing policy:

In the Available Policies region, expand Routing, hover over Gateway Based Routing, and then click Apply.
The Edit Policy dialog appears.
From the Apply Policy dialog:
1. (Optional) In the Your Policy Name field, enter a name for the policy.
2. (Optional) In the Comments field, describe why you are applying the policy for this API.
3. From the Place after the following policy list, select the policy after which this policy is placed in the request flow.
4. Click Next.
5. Click Select Gateways >. Select one or more gateways. Click the down arrow at the right of an gateway to view its description. If the list of gateways is long, you can use the search box at the top of the list to search for it by name. Click Select to return to the Apply Policy dialog.
6. (Optional) To drop or add/update headers, expand the Configure Headers section.
  - To drop headers, click the Drop Headers field to list header names to be deleted for this condition. Click in the field and select a header to drop. Repeat for each header you want to drop. You can also type the header name in the field and press Enter.
  - To add or update headers, click the Header Name list and select the header you want to add or update, or type the header name and press Enter. Enter a value for the header in the Header Value field. Click the + (Add new Header) icon to add more headers as needed, specifying the header name and value for each one you add.
7. In the Service section, choose one of the following:
  - Select Existing: Click the Select Service button to select a service from the list of services available. You can only add services for which you are issued the Manage Service or Reference Service grant.
  - Enter a URL: Use this option to enter a URL for the service. With this option, you can also select the Use Gateway Node Proxy option if a proxy is required to call the service from the gateway node your API will be deployed to.
    
    Gateway Managers with the Manage Gateway grant can configure proxies for gateway nodes they manage. This allows for different proxy configurations for dev and production gateways or different proxies for nodes located in separate data centers. If this option is selected, but no proxy is configured for a node the API is deployed to, the request is passed from the gateway node to the backend service without using a proxy.
8. (Optional) Click the Select Service Account button and select the service account containing credentials required to access the service. Note that selecting a service account here overrides any service account attached to the service, if you selected one above.
  
  You can only add service accounts for which you are issued the Manage Service Account or Reference Service Account grant.
9. (Optional) Click the + (Add a new condition) icon to add additional conditions. Repeat Steps 2d through 2h to populate the data for any additional conditions you add.
10. In the Otherwise section, choose one of the following behaviors to route all requests not matching the conditions you specified above:
  - (Default) Select Keep Default Service Request URL to route requests to the API’s default service request URL.
  - Select Configure Service Request to route requests to a specific service request. Configure headers, a service, and a service account as in the steps above.
11. Click Apply to save your changes and close the dialog, or click Apply as Draft to save a draft of your policy configuration.
Click Save.

The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

Apply Resource-Based Routing Policies

Use the Resource-based routing policy to route requests to specific resource paths to different service request URLs.

If the specification for the API was created in and loaded from Apiary, you can use the actions from the API in this policy.

This policy can be added only to the request flow.

This task assumes that you are already viewing the API Implementation tab for an API. To navigate to this tab, first select an API from the APIs list page, and then click the

API Implementation tab.

To configure a resource-based routing policy:

In the Available Policies region, expand Routing, hover over Resource-Based Routing, and then click Apply.
The Apply Policy dialog appears.
From the Apply Policy dialog:
1. (Optional) In the Your Policy Name field, enter a name for the policy.
2. (Optional) In the Comments field, describe why you are applying the policy for this API.
3. From the Place after the following policy list, select the policy after which this policy is placed in the request flow.
4. Click Next.
5. If the API was created with an Apiary specification, the Resource Configuration section appears with theFrom API Spec selected. You can configure the resources using actions from the API specification by following Step f below. If you want to configure the resources manually, click the Manual option and follow Step g below.
6. From the Resource Option list, select Actions, Resource Paths, or Methods.
  - If you selected Actions, click Select Actions > to display the list of actions. Select the desired action or actions, or use the Select All option at the bottom of the list. Click Select to return to the Apply Policy dialog. You can also filter the list of actions using the search box at the top.
  - If you selected Resource Paths, click Resources > to display the list of resources. Select the desired resource or resources, or use the Select All option at the bottom of the list. Click Select to return to the Apply Policy dialog. You can filter the list of resources using the search box at the top.
  - If you selected Methods, click in the Select Methods box to display a list of methods. Select as many methods, one at a time, as desired.
7. Click the Resource Option list, and select Methods and Resource Paths, Resource Paths, or Methods.
  - If you selected Methods and Resource Paths, click the Method list and select a method. In the Resource Path field, type the resource path(s) (such as /estimate, including the slash). Click the + (Add a new method/path combination) icon to add additional combinations.
  - If you selected Resource Paths, type the resource path(s) (such as /estimate, including the slash), and press Enter. You can enter multiple resource paths. Press Enter after entering each resource path.
  - If you selected Methods, click in the Select Methods box to display a list of methods. Select as many methods, one at a time, as desired.
8. (Optional) To drop or add/update headers, expand the Configure Headers section.
  - To drop headers, click the Drop Headers field to list header names to be deleted for this condition. Click in the field and select a header to drop. Repeat for each header you want to drop. You can also type the header name in the field and press Enter.
  - To add or update headers, click the Header Name list and select the header you want to add or update, or type the header name and press Enter. Enter a value for the header in the Header Value field. Click the + (Add new Header) icon to add more headers as needed, specifying the header name and value for each one you add.
9. In the Service section, choose one of the following:
  - Select Existing: Click the Select Service button to select a service from the list of services available. You can only add services for which you are issued the Manage Service or Reference Service grant.
  - Enter a URL: Use this option to enter a URL for the service. With this option, you can also select the Use Gateway Node Proxy option if a proxy is required to call the service from the gateway node your API will be deployed to.
    
    Gateway Managers with the Manage Gateway grant can configure proxies for gateway nodes they manage. This allows for different proxy configurations for dev and production gateways or different proxies for nodes located in separate data centers. If this option is selected, but no proxy is configured for a node the API is deployed to, the request is passed from the gateway node to the backend service without using a proxy.
10. (Optional) Click the Select Service Account button and select the service account containing credentials required to access the service. Note that selecting a service account here overrides any service account attached to the service, if you selected one above.
  
  You can only add service accounts for which you are issued the Manage Service Account or Reference Service Account grant.
11. (Optional) Click the + (Add a new condition) icon to add additional conditions. Repeat Step 2e through Step 2h to populate the data for any additional conditions you add.
12. In the Otherwise section, choose one of the following behaviors to route all requests not matching the conditions you specified above:
  - (Default) Select Keep Default Service Request URL to route requests to the API’s default service request URL.
  - Select Configure Service Request to route requests to a specific service request. Configure headers, a service, and a service account as in the steps above.
13. Click Apply to save your changes and close the dialog, or click Apply as Draft to save a draft of your policy configuration.
Click Save.

The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

Apply Service Callout 2.0 Policies

Use a service callout policy to call external services from an API’s request flow. The gateway can pass or reject the request based on the status code received from the external system.

You can use a service callout policy to create an object in another system during the request flow. The service callout policy can use GET, PUT, POST or DELETE methods to call external services.

This policy can be added only to the request flow.

This task assumes that you are already viewing the API Implementation tab for an API. To navigate to this tab, first select an API from the APIs list page, and then click the

API Implementation tab.

To configure a service callout policy:

In the Available Policies region, expand Other, hover over Service Callout 2.0, and then click Apply.
The Apply Policy dialog appears.
From the Apply Policy dialog:
1. (Optional) In the Your Policy Name field, enter a name for the policy.
2. (Optional) In the Comments field, describe why you are applying the policy for this API.
3. From the Place after the following policy list, select the policy after which this policy is placed in the request flow.
4. Click Next.
5. Select PASS to pass, or select REJECT to reject, requests that meet the criteria configured in this policy.
6. Select Specific from the list, and then enter a status code into the Status Codes field that, when received, the request is passed or rejected as you specified above. You can enter multiple status codes in this field, separating each one by pressing Enter. Alternatively, select Any from the list to pass or reject the request if any status is received from the external service.
7. (Optional) Select the Include timeouts and exceptions as conditions option to use timeouts and other exceptions received from the external system to pass or reject requests. Deselect this option if you want to ignore timeouts and other exceptions.
8. From the Method list, select the method used to call the external service: GET, POST, PUT, or DELETE.
9. In the Service section, choose one of the following:
  - Select Existing: Click the Select Service button to select a service from the list of services available. You can only add services for which you are issued the Manage Service or Reference Service grant.
  - Enter a URL: Use this option to enter a URL for the service. With this option, you can also select the Use Gateway Node Proxy option if a proxy is required to call the service from the gateway node your API will be deployed to.
    
    Gateway Managers with the Manage Gateway grant can configure proxies for gateway nodes they manage. This allows for different proxy configurations for dev and production gateways or different proxies for nodes located in separate data centers. If this option is selected, but no proxy is configured for a node the API is deployed to, the request is passed from the gateway node to the backend service without using a proxy.
10. (Optional) Click the Select Service Account button and select the service account containing credentials required to access the service. Note that selecting a service account here overrides any service account attached to the service, if you selected one above.
  
  You can only add service accounts for which you are issued the Manage Service Account or Reference Service Account grant.
11. (Optional) To add or update headers, expand the Add/Update Headers section. Click the Header Name list and select the header you want to add or update, or type the header name and press Enter. Enter a value for the header in the Header Value field.
  
  Click the + (Add new Header) icon to add another header as desired and repeat this step for additional headers you want to send to the service. The policy supports passing the inbound headers with ${headers.headername}. For more information, see About Using Groovy in Policies
12. (Optional) In the Request Payload field, enter the request payload to send to the external service you want to call, if applicable. This payload can be JSON, XML, or another content type accepted by the service. This field is only available if you selected POST or PUT as the method in step 2h.
13. Click Apply to save your changes and close the dialog, or click Apply as Draft to save a draft of your policy configuration.
Click Save.

The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

Apply Groovy Script Policies

Use a Groovy Script policy to pass or reject a request by examining the request context or to manipulate the request context.

Time checks are complied the style of Java; therefore, Groovy meta object protocol is bypassed. This means the dynamic Groovy syntax is not supported, for example dev headerValue = context.apiRequest.headers.header1.

This policy can be added to the request or response flows.

This task assumes that you are already viewing the API Implementation tab for an API. To navigate to this tab, first select an API from the APIs list page, and then click the

API Implementation tab.

To configure a Groovy script policy:

In the Available Policies region, expand Other, hover over Groovy Script, and then click Apply.
The Apply Policy dialog appears.
From the Apply Policy dialog:
1. (Optional) In the Your Policy Name field, enter a name for the policy.
2. (Optional) In the Comments field, describe why you are applying the policy for this API.
3. From the Place after the following policy list, select the policy after which this policy is placed in the request or response flow.
4. Click Next.
5. In the Groovy Script field, enter the Groovy script that you want to run when a request reaches this point in the request or response flows.
6. Click Apply to save your changes and close the dialog, or click Apply as Draft to save a draft of your policy configuration.
Click Save.

The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

Example 4-2 Example of Header Validation Policy Configuration in JSON

The policy configuration would be part of an API configuration.

{
    type: "o:GroovyScript",
    name: "Groovy Script",
    version: "1.0",
    category: "@implementations.policyCategory.other",
    description: "Executes Groovy script",
    constraints: {
        direction: "REQUEST_OR_RESPONSE",
        singleton: false
    },
    ui: {
        edit: {
            html: "groovyscript-edit.html",
            js: "groovyscript-edit.js",
            helpInfo: "#helpInfo",
            helpUrl: "http://www.oracle.com",
            helpTopicId: ""
        },
        view: {
            html: "groovyscript-view.html",
            js: "groovyscript-view.js",
            helpInfo: "#helpInfo",
            helpUrl: "http://www.oracle.com",
            helpTopicId: ""
        },
        l10nbundle: "groovyscript.js"
    }
}

Example 4-3 Groovy Script Action Configuration in XML

This is the XML configuration that is required by OCSG gateway to configure the policy.

def xmlText1 = '''<?xml version="1.0" encoding="UTF-8" ?>
<OUT_PUT>
<id>12345678</id>
<name>freedom</name>
<email />
</OUT_PUT>'''
context.apiResponse.setBody(new StringBodyImpl(xmlText1, null))

Apply Logging Policies

Use a logging policy to log and store custom messages for APIs deployed to a specific gateway.

This policy can be added to the request or response flows.

This task assumes that you are already viewing the API Implementation tab for an API. To navigate to this tab, first select an API from the APIs list page, and then click the

API Implementation tab.

To configure a logging policy:

In the Available Policies region, expand Other, hover over Logging, and then click Apply.
The Apply Policy dialog appears.
From the Apply Policy dialog:
1. (Optional) In the Your Policy Name field, enter a name for the policy.
2. (Optional) In the Comments field, describe why you are applying the policy for this API.
3. From the Place after the following policy list, select the policy after which this policy is placed in the request or response flow.
4. Click Next.
5. In the Log Level list, select the level at which this message is logged: Info, Warning, Error, or Severe.
6. In the Log Message field, enter the message to be written to the log. Using Groovy notation, you can log values of headers, fields, or other values in the outbound request or inbound response. For example, to log the value of a tenant-id header sent with requests, enter tenant-id is ${headers.tenant-id}.
  Using this example, when a tenant-id header with a value of 2 is sent with a request, this line is written to the log file you specify in the next step:
```
[06-28 01:00:55: logging.LoggingValidationAction][[ACTIVE] ExecuteThread: '3' for queue: 'weblogic.kernel.Default (self-tuning)'] INFO  oracle.apiplatform.customlog  :  tenant-id is 2.
```
  A line is written for each request or response that reaches the Logging policy in the flow. Requests or responses rejected before the Logging policy executes are not logged. If a request or response does not include the header or field you specify (it is null or hidden by the Redaction policy), a line like this is written to the log:
```
[06-28 01:17:50: logging.LoggingValidationAction][[ACTIVE] ExecuteThread: '3' for queue: 'weblogic.kernel.Default (self-tuning)'] INFO  oracle.apiplatform.customlog  :  tenant-id is ' Failed to find: ${headers.tenant-id} '.
```
7. In the Log File Path field, enter the location to the log file you want to write messages to. This path is relative to this directory on the gateway node domain: domains/<name of the gateway domain>/apics/customlog/<test/ora.log>. For example, if you enter api.log, events are written to domains/<name of the gateway domain>/apics/customlog/api.log.
8. Click Apply to save your changes and close the dialog, or click Apply as Draft to save a draft of your policy configuration.
Click Save.

The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

Work with Draft Policies

You can save a draft policy if you want to save your work but have not yet completed configuring a policy.

Draft policies are not activated when an API is deployed to a gateway.

You can save a draft policy with validation errors; you must fix these errors before applying the policy and deploying the API to a gateway. The next time the API is deployed, the policies you’ve applied are activated.

This task assumes that you are already viewing the API Implementation tab for an API. To navigate to this tab, first select an API from the APIs list page, and then click the

API Implementation tab.

To apply and deploy a draft policy:

Hover over the draft policy you want to apply and click Edit.

Description of the illustration draft-policy.png
Make any changes that you want to the policy configuration.
Click Apply.
Click Save.
Deploy or redeploy the API.

Access Context Variables Using Groovy Notation

You can use Groovy notation to access dynamic contents like headers, query parameters, payloads and some context properties in specific policies.

These policies include:

Method Mapping
Service Callout
Logging
Redaction

Reserved Top-Level Variables

The following variables are reserved for system use and can be used in any policy that supports Groovy scripting:

headers: a map of incoming headers. Access a specific header with this syntax: ${headers.nameOfHeader}.
queries: a map of incoming query parameters. Access a specific query parameter with this syntax: ${queries.nameOfQueryParam}.
payload: the parsed XML or JSON payload. Access an element in the payload with this syntax: ${payload.invoice.quote}
msgProperties: a map of context properties. This variable is reserved but not implemented.

Note:

If the value of any of the dynamic entries are empty, null is used in place of the empty value. For example, if a policy accesses a header named tenant-id using the Groovy notation ${headers.tenant-id}, but the header is absent or has no value, this notation is evaluated as null.

Example 4-4 Creating a New Query Parameter with the Method Mapping Policy

The following example maps an incoming query parameter, abc, to a new query parameter, xyz. Instead of using the value of abc, the value of xyz will be the value of ${payload.invoice.quote} in the incoming payload.

Example 4-5 Creating a New Header with the Method Mapping Policy

The following example maps an incoming header, abc, to a new header, xyz. Instead of using the value of abc, the value of xyz will be the value of ${headers.abc} in the incoming payload.

Example 4-6 Constructing an XML Payload with the Service Callout Policy

The following example creates an XML payload using values from the outbound request sent to a deployed endpoint. The value of the customer.name field is mapped to a <user> XML element in the payload sent to an external service; the value of the customer.age field is mapped to an <age> element in the payload.

<output><user>${payload.customer.name}</user><age>${payload.customer.age}</age></output>

Example 4-7 Constructing a JSON Payload with the Service Callout Policy

The following example creates a JSON payload using values from the outbound request sent to a deployed endpoint. The value of the customer.name field is mapped to a user JSON object in the payload sent to an external service; the value of the customer.age field is mapped to an age object in the payload.

{"user":"${payload.customer.name}", "age":${payload.customer.age}}

Example 4-8 Logging Dynamic Values with the Logging Policy

The following example writes an entry to the log file every time the policy is triggered, replacing the Groovy variables with values from the introspected payload:

Got an order from ${payload.user}, the amount is ${payload.price}.