Adding Request Policies and Response Policies to API Deployment Specifications
Find out how to control the behavior of API deployments by adding request and response policies to API specifications that you previously created with API Gateway.
You can control the behavior of an API deployment you create on an API gateway by adding request and response policies to the API deployment specification:
- a request policy describes actions to be performed on an incoming request from an API client before it is sent to a back end
- a response policy describes actions to be performed on a response returned from a back end before it is sent to an API client
You can use request policies and/or response policies to:
- limit the number of requests sent to back-end services
- enable CORS (Cross-Origin Resource Sharing) support
- provide authentication and authorization
- add mTLS support
- validate requests before sending them to back-end services
- modify incoming requests and outgoing responses
- cache responses to improve performance and reduce load on back-end services
- make API deployments eligible for inclusion in usage plans that monitor and manage subscriber access
You can add policies to an API deployment specification that apply globally to all routes in the API deployment specification, as well as policies that apply only to particular routes.
Note that API Gateway request policies and response policies are different to IAM policies, which control access to Oracle Cloud Infrastructure resources.
You can add request and response policies to an API deployment specification by:
- using the Console
- editing a JSON file
Using the Console to Add Request Policies and Response Policies
To add request policies and response policies to an API deployment specification using the Console:
-
Create or update an API deployment using the Console, select the From Scratch option, and enter details on the Basic Information page.
For more information, see Deploying an API on an API Gateway by Creating an API Deployment and Updating an API Gateway or an API Deployment.
-
In the API Request Policies section of the Basic Information page, specify request policies that apply globally to all routes in the API deployment specification:
- Mutual-TLS: A policy to control access to APIs you deploy to API gateways based on the TLS certificate presented by the API client making a request. You can only apply an mTLS policy globally to all routes in the API deployment specification (not to individual routes). See Adding mTLS support to API Deployments.
- CORS: A policy to enable CORS support in the APIs you deploy to API gateways. You can also specify CORS policies that apply to individual routes in the API deployment specification (you don't need to have entered a global CORS policy first). See Adding CORS support to API Deployments.
- Rate Limiting: A policy to limit the rate at which API clients can make requests to back-end services. You can only apply a rate-limiting policy globally to all routes in the API deployment specification (not to individual routes). See Limiting the Number of Requests to API Gateway Back Ends.
-
Click Next to specify options to define a global authentication request policy on the Authentication page.
The authentication request policy controls access to the APIs you deploy to API gateways. Having specified a global authentication policy first, you can then specify authorization policies that apply to individual routes in the API deployment specification. See Adding Authentication and Authorization to API Deployments.
-
Click Next to enter details for individual routes in the API deployment on the Routes page.
-
To specify request policies that apply to an individual route, click Show Route Request Policies and specify:
- Authorization: A policy to specify the operations an end user is allowed to perform, based on the end user's access scopes. Note that you must have already specified a global authentication policy before you can specify an authorization policy on an individual route. See Adding Authentication and Authorization to API Deployments.
- CORS: A policy to enable CORS support for individual routes in the API deployment specification (you don't need to have entered a global CORS policy first). See Adding CORS support to API Deployments.
- Header Validations: A policy to validate headers in requests. See Using the Console to Add Validation Request Policies.
- Query Parameter Validations: A policy to validate query parameters in requests. See Using the Console to Add Validation Request Policies.
- Body Validation: A policy to validate the content in the body of requests. See Using the Console to Add Validation Request Policies
- Header Transformations: A policy to add, remove, and modify headers in requests. See Using the Console to Add Header Transformation Request Policies.
- Query Transformations: A policy to add, remove, and modify query parameters in requests. See Using the Console to Add Query Parameter Transformation Request Policies.
-
To specify response policies that apply to an individual route, click Show Route Response Policies and specify:
- Header Transformations: A policy to add, remove, and modify headers in responses. See Using the Console to Add Header Transformation Response Policies.
- Click Next to review the details you entered for the API deployment.
- Click Create or Save Changes to create or update the API deployment.
- (Optional) Confirm the API has been deployed successfully by calling it (see Calling an API Deployed on an API Gateway).
Editing a JSON File to Add Request Policies and Response Policies
To add request policies and response policies to an API deployment specification in a JSON file:
-
Using your preferred JSON editor, edit the existing API deployment specification to which you want to add a request policy or response policy, or create a new API deployment specification (see Creating an API Deployment Specification).
At a minimum, the API deployment specification will include a
routes
section containing:- A path. For example,
/hello
- One or more methods. For example,
GET
- A definition of a back end. For example, a URL, or the OCID of a function in OCI Functions.
For example, the following basic API deployment specification defines a simple Hello World serverless function in OCI Functions as a single back end:
{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" } } ] }
- A path. For example,
-
To add a request policy that applies globally to all routes in the API deployment specification:
-
Insert a
requestPolicies
section before theroutes
section. For example:{ "requestPolicies": {}, "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" } } ] }
-
Include a request policy in the
requestPolicies
section.For example, to limit the number of requests sent to all routes in an API deployment specification, you'd include the
rateLimiting
policy in therequestPolicies
section as follows:{ "requestPolicies": { "rateLimiting": { "rateKey": "CLIENT_IP", "rateInRequestsPerSecond": 10 } }, "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" } } ] }
For more information about the
rateLimiting
request policy, see Limiting the Number of Requests to API Gateway Back Ends.
-
-
To add a request policy that applies to an individual route in the API deployment specification:
-
Insert a
requestPolicies
section after the route'sbackend
section. For example:{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "requestPolicies": {} } ] }
-
Include a request policy in the
requestPolicies
section.For example, to enable CORS support in an API deployment for a particular route, you'd include the
cors
policy in therequestPolicies
section as follows:{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "requestPolicies": { "cors":{ "allowedOrigins": ["*", "https://oracle.com"], "allowedMethods": ["*", "GET"], "allowedHeaders": [], "exposedHeaders": [], "isAllowCredentialsEnabled": false, "maxAgeInSeconds": 3000 } } } ] }
For more information about the
cors
request policy, see Adding CORS support to API Deployments.
-
-
To add a response policy that applies to an individual route in the API deployment specification:
-
Insert a
responsePolicies
section after the route'sbackend
section. For example:{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "responsePolicies": {} } ] }
-
Include a response policy in the
responsePolicies
section.For example, to rename any
X-Username
header toX-User-ID
in the response from a particular route, you'd include theheaderTransformations
policy in theresponsePolicies
section as follows:{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "responsePolicies": { "headerTransformations": { "renameHeaders": { "items": [ { "from": "X-Username", "to": "X-User-ID" } ] } } } } ] }
For more information about the
headerTransformations
response policy, see Editing a JSON File to Add Header Transformation Response Policies.
-
- Save the JSON file containing the API deployment specification.
-
Use the API deployment specification when you create or update an API deployment in the following ways:
- by specifying the JSON file in the Console when you select the Upload an existing API option
- by specifying the JSON file in a request to the API Gateway REST API
For more information, see Deploying an API on an API Gateway by Creating an API Deployment.