Transforming Incoming Requests and Outgoing Responses
Find out how to modify incoming requests and outgoing responses being sent to and from back-end services with API Gateway.
There are often situations when you'll want an API gateway to modify incoming requests before sending them to back-end services. Similarly, you might want the API gateway to modify responses returned by back-end services. For example:
- Back-end services might require requests to include a particular set of HTTP headers (for example, Accept-Language and Accept-Encoding). To hide this implementation detail from API consumers and API clients, you can use your API gateway to add the required headers.
- Web servers often include full version information in response headers. For security reasons, you might want to prevent API consumers and API clients knowing about the underlying technology stack. You can use your API gateway to remove server headers from responses.
- Back-end services might include sensitive information in a response. You can use your API gateway to remove such information.
Using an API gateway, you can:
- Add, remove, and modify headers in requests and responses.
- Add, remove, and modify query parameters in requests.
- Rewrite request URLs from a public format to an internal format, perhaps to support legacy applications and migrations.
You use request and response policies to transform the headers and query parameters of incoming requests, and the headers of outgoing responses (see Adding Request Policies and Response Policies to API Deployment Specifications).
You can include context variables in header and query parameter transformation request and response policies. Including context variables enables you to modify headers and query parameters with the values of other headers, query parameters, path parameters, and authentication parameters. Note that values of context variable values are extracted from the original request or response, and are not subsequently updated as an API gateway uses a transformation policy to evaluate a request or response. For more information about context variables, see Adding Context Variables to Policies and HTTP Back End Definitions.
If a header or query parameter transformation request or response policy will result in an invalid header or query parameter, the transformation policy is ignored.
Note that you cannot use header transformation policies to transform certain protected request and response headers. See Protected Request Headers and Response Headers.
You can add header and query parameter transformation request and response policies to an API deployment specification by:
- using the Console
- editing a JSON file
Adding Header Transformation Request Policies
You can add header transformation request policies to API deployment specifications using the Console or by editing a JSON file.
Note that you cannot use header transformation policies to transform certain protected request headers. See Protected Request Headers and Response Headers.
Using the Console to Add Header Transformation Request Policies
To add header transformation request 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.
-
Click Next and specify authentication options on the Authentication page.
For more information about authentication options, see Adding Authentication and Authorization to API Deployments.
-
Click Next to enter details for individual routes in the API deployment on the Routes page.
- On the Routes page, select the route for which you want to specify header transformation request policies.
- Click Show Route Request Policies.
- Click the Add button beside Header Transformations to update the headers included in a request to the API gateway for the current route.
-
To limit the headers included in a request, specify:
- Action: Filter.
- Type: Either Block to remove from the request the headers you explicitly list, or Allow to only allow in the request the headers you explicitly list (any other headers are removed from the request).
-
Header Names: The list of headers to remove from the request or allow in the
request (depending on the setting of Type). The names you specify are not
case-sensitive, and must not be included in any other transformation request policies
for the route (with the exception of items you filter as allowed). For example,
User-Agent
.
-
To change the name of a header included in a request (whilst keeping its original value), specify:
- Action: Rename.
-
From: The original name of the header that you are renaming. The name you
specify is not case-sensitive, and must not be included in any other transformation
request policies for the route. For example,
X-Username
. -
To: The new name of the header you are renaming. The name you specify is not
case-sensitive (capitalization might be ignored), and must not be included in any
other transformation request policies for the route (with the exception of items you
filter as allowed). For example,
X-User-ID
.
-
To add a new header to a request (or to change or retain the values of an existing header already included in a request), specify:
- Action: Set.
-
Behavior: If the header already exists, specify what to do with the header's existing value:
- Overwrite, to replace the header's existing value with the value you specify.
- Append, to append the value you specify to the header's existing value.
- Skip, to keep the header's existing value.
-
Name: The name of the header to add to the request (or to change the value of).
The name you specify is not case-sensitive (capitalization might be ignored), and must
not be included in any other transformation request policies for the route (with the
exception of items you filter as allowed). For example,
X-Api-Key
. -
Values: The value of the new header (or the value to replace or append to an existing header's value, depending on the setting of Behavior). You can specify multiple values. The value you specify can be a simple string, or can include context variables (except for
request.body
) enclosed within${...}
delimiters. For example,"value": "zyx987wvu654tsu321"
,"value": "${request.path[region]}"
,"value": "${request.headers[opc-request-id]}"
.
- Click Save Changes, and then click Next to review the details you entered for individual routes.
- 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 Header Transformation Request Policies
To add header transformation request 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 header transformation request policies, or create a new API deployment specification (see Creating an API Deployment Specification).
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" } } ] }
-
Insert a
requestPolicies
section after thebackend
section for the route to which you want the header transformation request policy to apply. For example:{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "requestPolicies": {} } ] }
-
Add a
headerTransformations
section to therequestPolicies
section.{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "requestPolicies": { "headerTransformations":{} } } ] }
-
To limit the headers included in a request, specify a
filterHeaders
header transformation request policy:{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "requestPolicies": { "headerTransformations": { "filterHeaders": { "type": "<BLOCK|ALLOW>", "items": [ { "name": "<header-name>" } ] } } } } ] }
where:
"type": "<BLOCK|ALLOW>"
indicates what to do with the headers specified by"items":[{"name":"<header-name>"}]
:- Use
BLOCK
to remove from the request the headers you explicitly list. - Use
ALLOW
to only allow in the request the headers you explicitly list (any other headers are removed from the request).
- Use
"name":"<header-name>
is a header to remove from the request or allow in the request (depending on the setting of"type": "<BLOCK|ALLOW>"
). The name you specify is not case-sensitive, and must not be included in any other transformation request policies for the route (with the exception of items inALLOW
lists). For example,User-Agent
.
You can remove and allow up to 50 headers in a
filterHeaders
header transformation request policy.For example:
{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "requestPolicies": { "headerTransformations": { "filterHeaders": { "type": "BLOCK", "items": [ { "name": "User-Agent" } ] } } } } ] }
In this example, the API gateway removes the
User-Agent
header from all incoming requests. -
To change the name of a header included in a request (whilst keeping its original value), specify a
renameHeaders
header transformation request policy:{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "requestPolicies": { "headerTransformations": { "renameHeaders": { "items": [ { "from": "<original-name>", "to": "<new-name>" } ] } } } } ] }
where:
"from": "<original-name>"
is the original name of the header that you are renaming. The name you specify is not case-sensitive, and must not be included in any other transformation request policies for the route. For example,X-Username
."to": "<new-name>"
is the new name of the header you are renaming. The name you specify is not case-sensitive (capitalization might be ignored), and must not be included in any other transformation request policies for the route (with the exception of items inALLOW
lists). For example,X-User-ID
.
You can rename up to 20 headers in a
renameHeaders
header transformation request policy.For example:
{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "requestPolicies": { "headerTransformations": { "renameHeaders": { "items": [ { "from": "X-Username", "to": "X-User-ID" } ] } } } } ] }
In this example, the API gateway renames any
X-Username
header toX-User-ID
, whilst keeping the header's original value. -
To add a new header to a request (or to change or retain the values of an existing header already included in a request), specify a
setHeaders
header transformation request policy:{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "requestPolicies": { "headerTransformations": { "setHeaders": { "items": [ { "name": "<header-name>", "values": ["<header-value>"], "ifExists": "<OVERWRITE|APPEND|SKIP>" } ] } } } } ] }
where:
"name":"<header-name>
is the name of the header to add to the request (or to change the value of). The name you specify is not case-sensitive, and must not be included in any other transformation request policies for the route (with the exception of items inALLOW
lists). For example,X-Api-Key
."values": ["<header-value>"]
is the value of the new header (or the value to replace or append to an existing header's value, depending on the setting of"ifExists": "<OVERWRITE|APPEND|SKIP>"
). The value you specify can be a simple string, or can include context variables (except forrequest.body
) enclosed within${...}
delimiters. For example,"values": "zyx987wvu654tsu321"
,"values": "${request.path[region]}"
,"values": "${request.headers[opc-request-id]}"
.You can specify up to 10 values. If you specify multiple values, the API gateway adds a header for each value.
-
"ifExists": "<OVERWRITE|APPEND|SKIP>"
indicates what to do with the header's existing value if the header specified by<header-name>
already exists:- Use
OVERWRITE
to replace the header's existing value with the value you specify. - Use
APPEND
to append the value you specify to the header's existing value. - Use
SKIP
to keep the header's existing value.
If not specified, the default is
OVERWRITE
. - Use
You can add (or change the values of) up to 20 headers in a
setHeaders
header transformation request policy.For example:
{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "requestPolicies": { "headerTransformations": { "setHeaders": { "items": [ { "name": "X-Api-Key", "values": ["zyx987wvu654tsu321"], "ifExists": "OVERWRITE" } ] } } } } ] }
In this example, the API gateway adds the
X-Api-Key:zyx987wvu654tsu321
header to all incoming requests. If an incoming request already has anX-Api-Key
header set to a different value, the API gateway replaces the existing value withzyx987wvu654tsu321
. - 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 and Updating an API Gateway or an API Deployment.
- (Optional) Confirm the API has been deployed successfully by calling it (see Calling an API Deployed on an API Gateway).
Adding Query Parameter Transformation Request Policies
You can add query parameter transformation request policies to API deployment specifications using the Console or by editing a JSON file.
Using the Console to Add Query Parameter Transformation Request Policies
To add query parameter transformation request 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.
-
Click Next and specify authentication options on the Authentication page.
For more information about authentication options, see Adding Authentication and Authorization to API Deployments.
-
Click Next to enter details for individual routes in the API deployment on the Routes page.
- On the Routes page, select the route for which you want to specify query parameter transformation request policies.
- Click Show Route Request Policies.
- Click the Add button beside Query Parameter Transformations to update the query parameters included in a request to the API gateway for the current route.
-
To limit the query parameters included in a request, specify:
- Action: Filter.
- Type: Either Block to remove from the request the query parameters you explicitly list, or Allow to only allow in the request the query parameters you explicitly list (any other query parameters are removed from the request).
-
Query Parameter Names: The list of query parameters to remove from the request
or allow in the request (depending on the setting of Type). The names you
specify are case-sensitive, and must not be included in any other transformation
request policies for the route (with the exception of items you filter as allowed)..
For example,
User-Agent
.
-
To change the name of a query parameter included in a request (whilst keeping its original value), specify:
- Action: Rename.
-
From: The original name of the query parameter that you are renaming. The name
you specify is case-sensitive, and must not be included in any other transformation
request policies for the route. For example,
X-Username
. -
To: The new name of the query parameter you are renaming. The name you specify
is case-sensitive (capitalization is respected), and must not be included in any other
transformation request policies for the route (with the exception of items you filter
as allowed). For example,
X-User-ID
.
-
To add a new query parameter to a request (or to change or retain the values of an existing query parameter already included in a request), specify:
- Action: Set.
-
Behavior: If the query parameter already exists, specify what to do with the query parameter's existing value:
- Overwrite, to replace the query parameter's existing value with the value you specify.
- Append, to append the value you specify to the query parameter's existing value.
- Skip, to keep the query parameter's existing value.
-
Query Parameter Name: The name of the query parameter to add to the request (or
to change the value of). The name you specify is case-sensitive, and must not be
included in any other transformation request policies for the route (with the
exception of items you filter as allowed). For example,
X-Api-Key
. -
Values: The value of the new query parameter (or the value to replace or append
to an existing query parameter's value, depending on the setting of Behavior).
The value you specify can be a simple string, or can include context variables
enclosed within
${...}
delimiters. For example,"value": "zyx987wvu654tsu321"
,"value": "${request.path[region]}"
,"value": "${request.headers[opc-request-id]}"
. You can specify multiple values.
- Click Save Changes, and then click Next to review the details you entered for individual routes.
- 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 Query Parameter Transformation Request Policies
To add query parameter transformation request 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 query parameter transformation request policies, or create a new API deployment specification (see Creating an API Deployment Specification).
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" } } ] }
-
Insert a
requestPolicies
section after thebackend
section for the route to which you want the query parameter transformation request policy to apply. For example:{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "requestPolicies": {} } ] }
-
Add a
queryParameterTransformations
section to therequestPolicies
section.{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "requestPolicies": { "queryParameterTransformations":{} } } ] }
-
To limit the query parameters included in a request, specify a
filterQueryParameters
query parameters transformation request policy:{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "requestPolicies": { "queryParameterTransformations": { "filterQueryParameters": { "type": "<BLOCK|ALLOW>", "items": [ { "name": "<query-parameter-name>" } ] } } } } ] }
where:
"type": "<BLOCK|ALLOW>"
indicates what to do with the query parameters specified by"items":[{"name":"<query-parameter-name>"}]
:- Use
BLOCK
to remove from the request the query parameters you explicitly list. - Use
ALLOW
to only allow in the request the query parameters you explicitly list (any other query parameters are removed from the request).
- Use
"name":"<query-parameter-name>
is a query parameter to remove from the request or allow in the request (depending on the setting of"type": "<BLOCK|ALLOW>"
). The name you specify is case-sensitive, and must not be included in any other transformation request policies for the route (with the exception of items inALLOW
lists). For example,User-Agent
.
You can remove and allow up to 50 query parameters in a
filterQueryParameters
query parameter transformation request policy.For example:
{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "requestPolicies": { "queryParameterTransformations": { "filterQueryParameters": { "type": "BLOCK", "items": [ { "name": "User-Agent" } ] } } } } ] }
In this example, the API gateway removes the
User-Agent
query parameter from all incoming requests. -
To change the name of a query parameter included in a request (whilst keeping its original value), specify a
renameQueryParameters
query parameter transformation request policy:{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "requestPolicies": { "queryParameterTransformations": { "renameQueryParameters": { "items": [ { "from": "<original-name>", "to": "<new-name>" } ] } } } } ] }
where:
"from": "<original-name>"
is the original name of the query parameter that you are renaming. The name you specify is case-sensitive, and must not be included in any other transformation request policies for the route. For example,X-Username
."to": "<new-name>"
is the new name of the query parameter you are renaming. The name you specify is case-sensitive (capitalization is respected), and must not be included in any other transformation request policies for the route (with the exception of items inALLOW
lists). For example,X-User-ID
.
You can rename up to 20 query parameters in a
renameQueryParameters
query parameter transformation request policy.For example:
{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "requestPolicies": { "queryParameterTransformations": { "renameQueryParameters": { "items": [ { "from": "X-Username", "to": "X-User-ID" } ] } } } } ] }
In this example, the API gateway renames any
X-Username
query parameter toX-User-ID
, whilst keeping the query parameter's original value. -
To add a new query parameter to a request (or to change or retain the values of an existing query parameter already included in a request), specify a
setQueryParameters
query parameter transformation request policy:{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "requestPolicies": { "queryParameterTransformations": { "setQueryParameters": { "items": [ { "name": "<query-parameter-name>", "values": ["<query-parameter-value>"], "ifExists": "<OVERWRITE|APPEND|SKIP>" } ] } } } } ] }
where:
"name": "<query-parameter-name>"
is the name of the query parameter to add to the request (or to change the value of). The name you specify is case-sensitive, and must not be included in any other transformation request policies for the route (with the exception of items inALLOW
lists). For example,X-Api-Key
."values": ["<query-parameter-value>"]
is the value of the new query parameter (or the value to replace or append to an existing query parameter's value, depending on the setting of"ifExists": "<OVERWRITE|APPEND|SKIP>"
). The value you specify can be a simple string, or can include context variables enclosed within${...}
delimiters. For example,"values": "zyx987wvu654tsu321"
,"values": "${request.path[region]}"
,"values": "${request.headers[opc-request-id]}"
.You can specify up to 10 values. If you specify multiple values, the API gateway adds a query parameter for each value.
-
"ifExists": "<OVERWRITE|APPEND|SKIP>"
indicates what to do with the query parameter's existing value if the query parameter specified by<query-parameter-name>
already exists:- Use
OVERWRITE
to replace the query parameter's existing value with the value you specify. - Use
APPEND
to append the value you specify to the query parameter's existing value. - Use
SKIP
to keep the query parameter's existing value.
If not specified, the default is
OVERWRITE
. - Use
You can add (or change the values of) up to 20 query parameters in a
setQueryParameters
query parameter transformation request policy.For example:
{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "requestPolicies": { "queryParameterTransformations": { "setQueryParameters": { "items": [ { "name": "X-Api-Key", "values": ["zyx987wvu654tsu321"], "ifExists": "OVERWRITE" } ] } } } } ] }
In this example, the API gateway adds the
X-Api-Key:zyx987wvu654tsu321
query parameter to all incoming requests. If an incoming request already has anX-Api-Key
query parameter set to a different value, the API gateway replaces the existing value withzyx987wvu654tsu321
. - 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 and Updating an API Gateway or an API Deployment.
- (Optional) Confirm the API has been deployed successfully by calling it (see Calling an API Deployed on an API Gateway).
Adding Header Transformation Response Policies
You can add header transformation response policies to API deployment specifications using the Console or by editing a JSON file.
Note that you cannot use header transformation policies to transform certain protected response headers. See Protected Request Headers and Response Headers.
Using the Console to Add Header Transformation Response Policies
To add header transformation 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.
-
Click Next and specify authentication options on the Authentication page.
For more information about authentication options, see Adding Authentication and Authorization to API Deployments.
-
Click Next to enter details for individual routes in the API deployment on the Routes page.
- On the Routes page, select the route for which you want to specify header transformation response policies.
- Click Show Route Response Policies.
- Click the Add button beside Header Transformations to update the headers included in a response from the API gateway for the current route.
-
To limit the headers included in a response, specify:
- Action: Filter.
- Type: Either Block to remove from the response the headers you explicitly list, or Allow to only allow in the response the headers you explicitly list (any other headers are removed from the response).
-
Header Names: The list of headers to remove from the response or allow in the
response (depending on the setting of Type). The names you specify are not
case-sensitive, and must not be included in any other transformation response policies
for the route (with the exception of items you filter as allowed). For example,
User-Agent
.
-
To change the name of a header included in a response (whilst keeping its original value), specify:
- Action: Rename.
-
From: The original name of the header that you are renaming. The name you
specify is not case-sensitive, and must not be included in any other transformation
response policies for the route. For example,
X-Username
. -
To: The new name of the header you are renaming. The name you specify is not
case-sensitive (capitalization might be ignored), and must not be included in any
other transformation response policies for the route (with the exception of items in
ALLOW
lists). For example,X-User-ID
.
-
To add a new header to a response (or to change or retain the values of an existing header already included in a response), specify:
- Action: Set.
-
Behavior: If the header already exists, specify what to do with the header's existing value:
- Overwrite, to replace the header's existing value with the value you specify.
- Append, to append the value you specify to the header's existing value.
- Skip, to keep the header's existing value.
-
Name: The name of the header to add to the response (or to change the value
of). The name you specify is not case-sensitive, and must not be included in any other
transformation response policies for the route (with the exception of items you filter
as allowed). For example,
X-Api-Key
. -
Values: The value of the new header (or the value to replace or append to an
existing header's value, depending on the setting of Behavior). The value you
specify can be a simple string, or can include context variables enclosed within
${...}
delimiters. For example,"value": "zyx987wvu654tsu321"
. You can specify multiple values.
- Click Save Changes, and then click Next to review the details you entered for individual routes.
- 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 Header Transformation Response Policies
To add header transformation 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 header transformation response policies, or create a new API deployment specification (see Creating an API Deployment Specification).
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" } } ] }
-
Insert a
responsePolicies
section after thebackend
section for the route to which you want the header transformation response policy to apply. For example:{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "responsePolicies": {} } ] }
-
Add a
headerTransformations
section to theresponsePolicies
section.{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "responsePolicies": { "headerTransformations":{} } } ] }
-
To limit the headers included in a response, specify a
filterHeaders
header transformation response policy:{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "responsePolicies": { "headerTransformations": { "filterHeaders": { "type": "<BLOCK|ALLOW>", "items": [ { "name": "<header-name>" } ] } } } } ] }
where:
"type": "<BLOCK|ALLOW>"
indicates what to do with the headers specified by"items":[{"name":"<header-name>"}]
:- Use
BLOCK
to remove from the response the headers you explicitly list. - Use
ALLOW
to only allow in the response the headers you explicitly list (any other headers are removed from the response).
- Use
"name":"<header-name>
is a header to remove from the response or allow in the response (depending on the setting of"type": "<BLOCK|ALLOW>"
). The name you specify is not case-sensitive, and must not be included in any other transformation response policies for the route (with the exception of items inALLOW
lists). For example,User-Agent
.
You can remove and allow up to 20 headers in a
filterHeaders
header transformation response policy.For example:
{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "responsePolicies": { "headerTransformations": { "filterHeaders": { "type": "BLOCK", "items": [ { "name": "User-Agent" } ] } } } } ] }
In this example, the API gateway removes the
User-Agent
header from all outgoing responses. -
To change the name of a header included in a response (whilst keeping its original value), specify a
renameHeaders
header transformation response policy:{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "responsePolicies": { "headerTransformations": { "renameHeaders": { "items": [ { "from": "<original-name>", "to": "<new-name>" } ] } } } } ] }
where:
"from": "<original-name>"
is the original name of the header that you are renaming. The name you specify is not case-sensitive, and must not be included in any other transformation response policies for the route. For example,X-Username
."to": "<new-name>"
is the new name of the header you are renaming. The name you specify is not case-sensitive (capitalization might be ignored), and must not be included in any other transformation response policies for the route (with the exception of items inALLOW
lists). For example,X-User-ID
.
You can rename up to 20 headers in a
renameHeaders
header transformation response policy.For example:
{ "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" } ] } } } } ] }
In this example, the API gateway renames any
X-Username
header toX-User-ID
, whilst keeping the header's original value. -
To add a new header to a response (or to change or retain the values of an existing header already included in a response), specify a
setHeaders
header transformation response policy:{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "responsePolicies": { "headerTransformations": { "setHeaders": { "items": [ { "name": "<header-name>", "values": ["<header-value>"], "ifExists": "<OVERWRITE|APPEND|SKIP>" } ] } } } } ] }
where:
"name":"<header-name>
is the name of the header to add to the response (or to change the value of). The name you specify is not case-sensitive, and must not be included in any other transformation response policies for the route (with the exception of items inALLOW
lists). For example,X-Api-Key
."values": ["<header-value>"]
is the value of the new header (or the value to replace or append to an existing header's value, depending on the setting of"ifExists": "<OVERWRITE|APPEND|SKIP>"
). The value you specify can be a simple string, or can include context variables enclosed within${...}
delimiters. For example,"values": "zyx987wvu654tsu321"
.You can specify up to 10 values. If you specify multiple values, the API gateway adds a header for each value.
-
"ifExists": "<OVERWRITE|APPEND|SKIP>"
indicates what to do with the header's existing value if the header specified by<header-name>
already exists:- Use
OVERWRITE
to replace the header's existing value with the value you specify. - Use
APPEND
to append the value you specify to the header's existing value. - Use
SKIP
to keep the header's existing value.
If not specified, the default is
OVERWRITE
. - Use
You can add (or change the values of) up to 20 headers in a
setHeaders
header transformation response policy.For example:
{ "routes": [ { "path": "/hello", "methods": ["GET"], "backend": { "type": "ORACLE_FUNCTIONS_BACKEND", "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq" }, "responsePolicies": { "headerTransformations": { "setHeaders": { "items": [ { "name": "X-Api-Key", "values": ["zyx987wvu654tsu321"], "ifExists": "OVERWRITE" } ] } } } } ] }
In this example, the API gateway adds the
X-Api-Key:zyx987wvu654tsu321
header to all outgoing responses. If an outgoing response already has anX-Api-Key
header set to a different value, the API gateway replaces the existing value withzyx987wvu654tsu321
. - 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 and Updating an API Gateway or an API Deployment.
- (Optional) Confirm the API has been deployed successfully by calling it (see Calling an API Deployed on an API Gateway).
Examples
The examples in this section assume the following API deployment definition and basic API deployment specification in a JSON file:
{
"displayName": "Marketing Deployment",
"gatewayId": "ocid1.apigateway.oc1..aaaaaaaab______hga",
"compartmentId": "ocid1.compartment.oc1..aaaaaaaa7______ysq",
"pathPrefix": "/marketing",
"specification": {
"routes": [
{
"path": "/weather",
"methods": ["GET"],
"backend": {
"type": "HTTP_BACKEND",
"url": "https://api.weather.gov"
},
"requestPolicies": {}
}
]
},
"freeformTags": {},
"definedTags": {}
}
Note the examples also apply when you're defining an API deployment specification using dialogs in the Console.
Example 1: Transforming header parameters to query parameters
In this example, assume an existing HTTP back end only handles requests containing query parameters, not header parameters. However, you want the HTTP back end to handle requests that include header parameters. To achieve this, you create an API deployment specification that includes a query parameter transformation request policy to pass the value obtained from a request header to the HTTP back end as a query parameter.
"requestPolicies": {
"queryParameterTransformations": {
"setQueryParameters": {
"items": [
{
"name": "region",
"values": ["${request.headers[region]}"],
"ifExists": "OVERWRITE"
}
]
}
}
}
In this example, a request like curl -H "region: west"
https://<gateway-hostname>/marketing/weather
resolves to
https://api.weather.gov?region=west
.
Example 2: Transforming one header to a different header
In this example, assume an existing HTTP back end only handles requests containing a particular header. However, you want the HTTP back end to handle requests that include a different header. To achieve this, you create an API deployment specification that includes a header transformation request policy to take the value obtained from one request header and pass it to the HTTP back end as a different request header.
"requestPolicies": {
"headerTransformations": {
"setHeaders": {
"items": [
{
"name": "region",
"values": ["${request.headers[locale]}"],
"ifExists": "OVERWRITE"
}
]
}
}
}
In this example, a request like curl -H "locale: west"
https://<gateway-hostname>/marketing/weather
resolves to the request
curl -H "region: west" https://api.weather.gov
.
Example 3: Adding an authentication parameter obtained from a JWT as a request header
In this example, assume an existing HTTP back end requires the value of the
sub
claim in a validated JSON Web Token (JWT) to be included in a request
as a header with the name JWT_SUBJECT. The API Gateway service has saved the value of the
sub
claim included in the JWT as an authentication parameter in the
request.auth
table.
To include the value of sub
in a header named JWT_SUBJECT, you create an
API deployment specification that includes a header transformation request policy. The
request policy obtains the sub
value from the request.auth
table and passes it to the HTTP back end as the value of the JWT_SUBJECT header.
"requestPolicies": {
"headerTransformations": {
"setHeaders": {
"items": [
{
"name": "JWT_SUBJECT",
"values": ["${request.auth[sub]}"],
"ifExists": "OVERWRITE"
}
]
}
}
}
In this example, when a request has been successfully validated, the JWT_SUBJECT header is added to the request passed to the HTTP back end.
Example 4: Adding a key obtained from an authorizer function as a query parameter
In this example, assume an existing HTTP back end requires requests to include a query
parameter named access_key
for authentication purposes. You want the
access_key
query parameter to have the value of a key named
apiKey
that has been returned by an authorizer function that has
successfully validated the request. The API Gateway service has saved the
apiKey
value as an authentication parameter in the
request.auth
table.
To include the access_key
query parameter in the request, you create an
API deployment specification that includes a query parameter transformation request policy.
The request policy obtains the apiKey
value from the
request.auth
table and passes it to the HTTP back end as the value of the
access_key
query parameter.
"requestPolicies": {
"queryParameterTransformations": {
"setQueryParameters": {
"items": [
{
"name": "access_key",
"values": ["${request.auth[apiKey]}"],
"ifExists": "OVERWRITE"
}
]
}
}
}
In this example, the access_key
query parameter is added to the request
passed to the HTTP back end, with the apiKey
value from the
request.auth
table. A request like
https://<gateway-hostname>/marketing/weather
resolves to a request
like https://api.weather.gov?access_key=fw5n9abi0ep
Example 5: Adding a default value for an optional query parameter
In this example, assume an existing HTTP back end requires requests to include a query
parameter named country
. However, the country
query
parameter is optional, and it's not included by some of the API clients sending requests. If
a request already includes a country
query parameter and a value, you want
both passed as-is to the HTTP back end. However, if a request doesn't already include a
country
query parameter, you want the country
query
parameter and a default value added to the request.
To make sure every request includes a country
query parameter, you create
an API deployment specification that includes a query parameter transformation request
policy. The request policy adds the country
query parameter and a default
value to any requests that do not already include the country
query
parameter.
"requestPolicies": {
"queryParameterTransformations": {
"setQueryParameters": {
"items": [
{
"name": "country",
"values": ["usa"],
"ifExists": "SKIP"
}
]
}
}
}
In this example, a request like
https://<gateway-hostname>/marketing/weather
resolves to
https://api.weather.gov?country=usa
. A request like
https://<gateway-hostname>/marketing/weather?country=canada
resolves to https://api.weather.gov?country=canada
.
Protected Request Headers and Response Headers
You cannot use header transformation policies to transform certain protected request and response headers, as follows:
Header | Protected as Request Header | Protected as Response Header |
---|---|---|
access-control-allow-credentials | not applicable | Yes |
access-control-allow-headers | not applicable | Yes |
access-control-allow-methods | not applicable | Yes |
access-control-allow-origin | not applicable | Yes |
access-control-expose-headers | not applicable | Yes |
access-control-max-age | not applicable | Yes |
cdn-loop | Yes | not applicable |
connection | Yes | Yes |
content-length | Yes | Yes |
cookie | Yes | not applicable |
except | Yes | Yes |
keep-alive | Yes | Yes |
opc-request-id | Yes | Yes |
origin | Yes | not applicable |
proxy-authenticate | not applicable | Yes |
proxy-authorization | Yes | not applicable |
public-key-pins | not applicable | Yes |
retry-after | not applicable | Yes |
strict-transport-security | not applicable | Yes |
te | Yes | Yes |
trailers | not applicable | Yes |
transfer-encoding | Yes | Yes |
upgrade | Yes | Yes |
x-content-type-options | not applicable | Yes |
x-forwarded-for | Yes | not applicable |
x-frame-options | not applicable | Yes |
x-real-ip | Yes | not applicable |
x-xss-protection | not applicable | Yes |