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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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. 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.
This policy can be added only to the request flow.
Apply Header Field Filtering Policies
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 policy can be added only to the request flow.
To configure a header field filtering policy: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.
Apply Redaction Policies
This policy can be added to the request or response flows.
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 |
---|---|---|
operation: exclude condition: a.c |
|
|
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 |
---|---|---|
operation: include only condition: [1].c.d Note: The array item count will be changed in this case. |
|
|
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 |
---|---|---|
operation: include only condition: root.a.e.element[0].f |
|
|
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 |
---|---|---|
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 |
|
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.
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.
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.
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 havexyz=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 thexyz
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 headerxyz
. 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 notx-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 havexyz=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 thexyz
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 parameterdepartment
. 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 notdept
, then the original query parameter is not replaced or removed. If there is a key value pair for examplekey=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.
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.
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.
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.
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.
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.
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.
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.
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.
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}.