Implementing 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 Configuring the API Request URL and Configuring 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.

Understanding 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. See Policy Placement to learn more about policy placement.

API Platform Cloud Service provides these types of policies:

Configuring 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. See Policy Placement for a list of policies that can be placed in the response pipeline and their valid locations. 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.

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

Note:

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. See Policy Placement for a list of policies that can be placed in the response pipeline and their valid locations.

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

-

150

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

-

Service Level Authorization

40

-

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

-

150

Service Request

100

-

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

Configuring 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 open an API from the APIs tab, and then click the API Implementation tab.
To configure the API Request URL:
  1. Hover over API Request and then click Edit.
    The Edit Policy dialog appears.
  2. 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. Click Next.
    4. From the Protocol list, select the protocol over which the gateway receives requests for the API. Your options are HTTP, HTTPS, or HTTP & HTTPS.
    5. In the API Endpoint URL field, enter the endpoint URL for this API. This is case sensitive; energy and Energy are considered different endpoints.

      Restriction:

      The following endpoints are reserved for internal use: /apiplatform and /prm_pm_rest. Do not use these values as endpoints for your APIs.

    6. 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.
The API Request URL is configured.

Important:

The API Implementation is not valid until you also configure the service request, as described in Configuring the Service Request URL. 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. See Documenting an API.

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

Note:

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. See Are SOAP APIs Supported?.

This task assumes that you are already viewing the API Implementation tab for an API. To navigate to this tab, first open an API from the APIs tab, and then click the API Implementation tab.
To configure the service request:
  1. Hover over the Service Request region, and then click Edit.
    The Edit Policy dialog appears.
  2. From the Edit 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. Click Next.
    4. Expand the Configure Headers section.
    5. In the all the Headers list, select Pass through or Drop.
    6. 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.
    7. 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.
    8. 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. .
    9. (Optional) Click the + (Add new Header) icon to add more headers as needed. Repeat Step 2h for each header you add.
    10. In the Service section, choose one of the following:
      • Select Existing: Use this option 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. See Creating a Service and Issuing Service Grants.

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

        Note: 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. See Configuring a Proxy for a Gateway Node.

    11. (Optional) From the Service Account list, 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. See Creating a Service Account and Understanding Service Account Grants.

    12. 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.
The service request URL is configured.

Important:

The API Implementation is not valid until you also configure the API request, as described in Configuring the API Request URL. You cannot deploy it to a gateway until you configure the API request.

Applying 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. See Configuring OAuth Providers. 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 open an API from the APIs tab, and then click the API Implementation tab.
To configure an OAuth 2.0 policy:
  1. In the Available Policies region, expand Security, hover over OAuth 2.0, and then click Apply.
    The Apply Policy dialog appears.
  2. 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. See Working with Draft Policies.
  3. Click Save Changes.
The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

Applying 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 open an API from the APIs tab, and then click the API Implementation tab.
To configure a key validation policy:
  1. In the Available Policies region, expand Security, hover over Key Validation, and then click Apply.

    Note:

    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.
  2. 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. See Working with Draft Policies.
  3. Click Save Changes.
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. See Signing in to the Load Balancer Console for Your 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 open an API from the APIs tab, and then click the API Implementation tab.
To configure an IP filter validation policy:
  1. In the Available Policies region, expand Security, hover over IP Filter Validation, and then click Apply.
    The Apply Policy dialog appears.
  2. 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. See Working with Draft Policies.
  3. Click Save Changes.
The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

Applying 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 open an API from the APIs tab, and then click the API Implementation tab.
To apply a basic authentication policy:
  1. In the Available Policies region, expand Security, hover over Basic Auth, and then click Apply.
    The Apply Policy dialog appears.
  2. 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. See Working with Draft Policies.
  3. Click Save Changes.
The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

Applying Service Level Auth Policies

Use the Service Level Auth policy to pass credentials to backend services secured with basic auth or OAuth 2.0.

Deprecation Notice

The Service Level Auth policy is deprecated in favor of adding service accounts to the Service Request URL or Service Callout policies. This policy will be removed in a future release. See:

You supply the credentials (username and password for basic auth or token URL, client ID, client secret, scope, and grant type for OAuth 2.0) required to access the service. Because you supply these credentials at design time, API consumers can access secured services (through the gateway intermediary) without specific knowledge of the credentials. This data is passed with the request to the service you specified in the Service Request URL. See Configuring the Service Request URL.

Policy limitations: In the case of OAuth, the accessToken is stored until it expires. When it expires, a new token is retrieved. If a token is revoked by any means, invocations will fail. Subsequent invocations fail until the existing token expires and a new one is retrieved.

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 open an API from the APIs tab, and then click the API Implementation tab.
To configure a service level authorization policy:
  1. In the Available Policies region, expand Security, hover over Service Level Authorization, and then click Apply.
    The Apply Policy dialog appears.
  2. 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 Account Auth Type list, select the type of authentication required to access your service: Basic Auth or OAuth 2.0.
    6. If you selected Basic Auth, populate the Username and Password fields with the credentials of a user authorized to access the service.

      Tip:

      While entering a password, toggle the Show Password switch to view the text you’re entering. For security purposes, you can’t use this option to view a password that was previously entered; for example, if you enter a password, apply your changes and close the dialog, the Show Password switch is disabled when you reopen the Apply Policy dialog.

    7. If you selected OAuth 2.0, select Add Token to URL to pass the access token in the URL via an access_token query parameter or select Add Token to Header to pass the token in an Authorization header (like Authorization: Bearer afdas87ohds9y.ulksdjfa9suqwef).
    8. If you selected OAuth 2.0. populate the Token URL, Client ID, Client Secret, and Scope fields with values pertinent to your service:

      Token URL is the URL used to get the access token.

      Client ID and Client Secret are the credentials of the application as which the API acts. The client ID/client secret combo is used to retrieve the access token from the OAuth provider.

      Scope is the OAuth scope for the backend service.

      Grant Type is the grant type used for authentication.

    9. From the Grant Type list, select Client Credentials or Resource Owner Password Credentials. If you selected Resource Owner Password Credentials, enter the user name and password of the resource owner.
    10. 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.
  3. Click Save Changes.
The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

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

Note:

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 open an API from the APIs tab, and then click the API Implementation tab.
To configure a CORS policy:
  1. In the Available Policies region, expand Security, hover over CORS, and then click Apply.
    The Apply Policy dialog appears.
  2. 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. See Working with Draft Policies.
  3. Click Save Changes.
The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

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

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

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 open an API from the APIs tab, and then click the API Implementation tab.
To configure an API throttling-delay policy:
  1. In the Available Policies region, expand Traffic Management, hover over API Throttling–Delay, and then click Apply.
    The Apply Policy dialog appears.
  2. 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 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.
    6. Enter a positive integer.
    7. 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.

    8. In the Delay requests by field, enter a value to delay requests by. This value must be an integer.
    9. 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.
    10. (Optional) Click the + (Add a new condition) icon to add additional conditions. Repeat Step 2d through Step 2i for each condition 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. See Working with Draft Policies.
  3. Click Save Changes.
The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

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

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. See Applying API Rate Limiting Policies.

Note:

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 open an API from the APIs tab, and then click the API Implementation tab.
To configure an application rate limiting policy:
  1. In the Available Policies region, expand Traffic Management, hover over Application Rate Limiting, and then click Apply.
    The Apply Policy dialog appears.
  2. 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 Rate Limit Per Application field, enter a positive integer.
    6. 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.
    7. (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.
    8. 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.
  3. Click Save Changes.
The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

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

Gateways reject requests exceeding any of the thresholds you set.

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. See Applying Application Rate Limiting Policies.

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 open an API from the APIs tab, and then click the API Implementation tab.
To configure an API rate limiting policy:
  1. In the Available Policies region, expand Traffic Management, hover over API Rate Limiting, and then click Apply.
    The Apply Policy dialog appears.
  2. 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 API Rate Limit field, enter a positive integer.
    6. 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.
    7. (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.
    8. 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.
  3. Click Save Changes.
The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

Applying 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 open an API from the APIs tab, and then click the API Implementation tab.
To configure an interface filtering policy:
  1. In the Available Policies region, expand Interface Management, hover over Interface Filtering, and then click Apply.
    The Apply Policy dialog appears.
  2. 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.

      Note:

      Wildards 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.
    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. See Working with Draft Policies.
  3. Click Save Changes.
The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

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

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 open an API from the APIs tab, and then click the API Implementation tab.
To configure a method mapping policy:
  1. In the Available Policies region, expand Interface Management, hover over Method Mapping, and then click Apply.
    The Apply Policy dialog appears.
  2. 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 column, select the resources(s) to change.
    6. In the Resource field in the Service column, select the resource to request from the service.
    7. In the Method(s) field in the API column, select the method(s) to change.
    8. In the Method field in the Service column, select the method to send requests with to the service. Select Keep Same to retain the value selected in the API column.
    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. See Working with Draft Policies.
  3. Click Save Changes.
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}

Applying Redaction Policies

Use a redaction policy to manage the fields and headers that appear in the request or response payload. You can explicitly include or exclude the headers and fields sent to the backend service (from the request flow) or sent to the client (from the response flow).

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 open an API from the APIs tab, and then click the API Implementation tab.
To configure a field redaction policy:
  1. In the Available Policies region, expand Interface Management, hover over Redaction, and then click Apply.
    The Apply Policy dialog appears.
  2. 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.
    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. See Working with Draft Policies.
  3. Click Save Changes.
The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

Applying 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 open an API from the APIs tab, and then click the API Implementation tab.
To configure a header validation policy:
  1. In the Available Policies region, expand Interface Management, hover over Header Validation, and then click Apply.
    The Apply Policy dialog appears.
  2. 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.

    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.

    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. See Working with Draft Policies.
  3. Click Save Changes.
The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

Applying 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 open an API from the APIs tab, and then click the API Implementation tab.
To configure a header-based routing policy:
  1. In the Available Policies region, expand Routing, hover over Header Based Routing, and then click Apply.
    The Edit Policy dialog appears.
  2. 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: Use this option 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. See Creating a Service and Issuing Service Grants.

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

        Note: 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. See Configuring a Proxy for a Gateway Node.

    10. (Optional) From the Service Account list, 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. See Creating a Service Account and Understanding Service Account Grants.

    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. See Working with Draft Policies.
  3. Click Save Changes.
The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

Applying 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 open an API from the APIs tab, and then click the API Implementation tab.
To configure a gateway-based routing policy:
  1. In the Available Policies region, expand Routing, hover over Gateway Based Routing, and then click Apply.
    The Edit Policy dialog appears.
  2. 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 Gateways list, select a gateway onto which the API is deployed that you want to route to a different service response URL, and then press Enter.

      You can enter multiple gateways. Press Enter after entering each gateway. Remove a gateway by clicking the X next to it.

    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: Use this option 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. See Creating a Service and Issuing Service Grants.

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

        Note: 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. See Configuring a Proxy for a Gateway Node.

    8. (Optional) From the Service Account list, 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. See Creating a Service Account and Understanding Service Account Grants.

    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. See Working with Draft Policies.
  3. Click Save Changes.
The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

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

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 open an API from the APIs tab, and then click the API Implementation tab.
To configure an application-based routing policy:
  1. In the Available Policies region, expand Routing, hover over Application-Based Routing, and then click Apply.
    The Edit Policy dialog appears.
  2. 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.

      Note:

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

    4. Click Next.
    5. In the Applications list, select the application from which you want to route requests to a different service response URL.

      You can enter multiple applications. Requests from all applications you enter in a single field are routed to the same Service URL. Press Enter after entering each application. Remove an application by clicking the X next to it.

    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: Use this option 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. See Creating a Service and Issuing Service Grants.

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

        Note: 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. See Configuring a Proxy for a Gateway Node.

    8. (Optional) From the Service Account list, 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. See Creating a Service Account and Understanding Service Account Grants.

    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. See Working with Draft Policies.
  3. Click Save Changes.
The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

Applying Resource-Based Routing Policies

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

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 open an API from the APIs tab, and then click the API Implementation tab.
To configure a resource-based routing policy:
  1. In the Available Policies region, expand Routing, hover over Resource-Based Routing, and then click Apply.
    The Apply Policy dialog appears.
  2. 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 Resource Paths 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.


      Description of remove-resource-path.png follows
      Description of the illustration remove-resource-path.png
    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: Use this option 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. See Creating a Service and Issuing Service Grants.

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

        Note: 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. See Configuring a Proxy for a Gateway Node.

    8. (Optional) From the Service Account list, 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. See Creating a Service Account and Understanding Service Account Grants.

    9. (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.
    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. See Working with Draft Policies.
  3. Click Save Changes.
The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

Applying 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 open an API from the APIs tab, and then click the API Implementation tab.
To configure a service callout policy:
  1. In the Available Policies region, expand Other, hover over Service Callout 2.0, and then click Apply.
    The Apply Policy dialog appears.
  2. 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: Use this option 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. See Creating a Service and Issuing Service Grants.

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

        Note: 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. See Configuring a Proxy for a Gateway Node.

    10. (Optional) From the Service Account list, 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. See Creating a Service Account and Understanding Service Account Grants.

    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.

    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. See Working with Draft Policies.
  3. Click Save Changes.
The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

Applying Service Callout 1.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 also 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 open an API from the APIs tab, and then click the API Implementation tab.
To configure a service callout policy:
  1. In the Available Policies region, expand Other, hover over Service Callout 1.0, and then click Apply.
    The Apply Policy dialog appears.
  2. 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 URL field, enter the URL of the service you want to call.
    10. (Optional) 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. See Configuring a Proxy for a Gateway Node.
    11. (Optional) In the Headers section, click the + (Add a new header icon), and then enter a header key:value pair to send to the service in the following format: Content-Type:application/json.

      Repeat this step for additional headers you want to send to the service.

    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. See Working with Draft Policies.
  3. Click Save Changes.
The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

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

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 open an API from the APIs tab, and then click the API Implementation tab.
To configure a Groovy script policy:
  1. In the Available Policies region, expand Other, hover over Groovy Script, and then click Apply.
    The Apply Policy dialog appears.
  2. 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. See Working with Draft Policies.
  3. Click Save Changes.
The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

Applying 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 open an API from the APIs tab, and then click the API Implementation tab.
To configure a logging policy:
  1. In the Available Policies region, expand Other, hover over Logging, and then click Apply.
    The Apply Policy dialog appears.
  2. 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}. See About Using Groovy in Policies to learn about using Groovy notation with this policy.

      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 path 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. See Working with Draft Policies.
  3. Click Save Changes.
The policy is now added to the API. It is activated when the API is (re)deployed to a gateway.

Working 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 open an API from the APIs tab, and then click the API Implementation tab.
To apply and deploy a draft policy:
  1. Hover over the draft policy you want to apply and click Edit.

    On the API Implementations tab, draft policies are displayed with a dotted-line border.

    Description of draft-policy.png follows
    Description of the illustration draft-policy.png
  2. Make any changes that you want to the policy configuration.
  3. Click Apply.
  4. Click Save Changes.
  5. Deploy or redeploy the API, as described in Deploying or Redeploying an API Endpoint to a Gateway.

About Using Groovy in Policies

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

  • Groovy Script

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-1 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-2 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}/Something in the incoming payload.

Example 4-3 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-4 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-5 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}.