Oracle Cloud Infrastructure Documentation

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:

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

  2. Click Next and specify authentication options on the Authentication page.

    For more information about authentication options, see Adding Authentication and Authorization to API Deployments.

  3. Click Next to enter details for individual routes in the API deployment on the Routes page.

  4. On the Routes page, select the route for which you want to specify header transformation request policies.
  5. Click Show Route Request Policies.
  6. Click the Add button beside Header Transformations to update the headers included in a request to the API gateway for the current route.

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

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

  9. 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]}".
  10. Click Save Changes, and then click Next to review the details you entered for individual routes.
  11. Click Create or Save Changes to create or update the API deployment.
  12. (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:

  1. 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"
      }
    }
  ]
}

  2. Insert a requestPolicies section after the backend 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": {}
    }
  ]
}

  3. Add a headerTransformations section to the requestPolicies section.

    {
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "headerTransformations":{}
      }
    }
  ]
}

  4. 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).
    • "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 in ALLOW 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.

  5. 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 in ALLOW 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 to X-User-ID, whilst keeping the header's original value.

  6. 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 in ALLOW 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 for request.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.

    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 an X-Api-Key header set to a different value, the API gateway replaces the existing value with zyx987wvu654tsu321.

  7. Save the JSON file containing the API deployment specification.

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

  9. (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:

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

  2. Click Next and specify authentication options on the Authentication page.

    For more information about authentication options, see Adding Authentication and Authorization to API Deployments.

  3. Click Next to enter details for individual routes in the API deployment on the Routes page.

  4. On the Routes page, select the route for which you want to specify query parameter transformation request policies.
  5. Click Show Route Request Policies.
  6. 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.

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

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

  9. 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.
  10. Click Save Changes, and then click Next to review the details you entered for individual routes.
  11. Click Create or Save Changes to create or update the API deployment.
  12. (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:

  1. 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"
      }
    }
  ]
}

  2. Insert a requestPolicies section after the backend 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": {}
    }
  ]
}

  3. Add a queryParameterTransformations section to the requestPolicies section.

    {
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "requestPolicies": {
        "queryParameterTransformations":{}
      }
    }
  ]
}

  4. 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).
    • "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 in ALLOW 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.

  5. 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 in ALLOW 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 to X-User-ID, whilst keeping the query parameter's original value.

  6. 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 in ALLOW 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.

    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 an X-Api-Key query parameter set to a different value, the API gateway replaces the existing value with zyx987wvu654tsu321.

  7. Save the JSON file containing the API deployment specification.

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

  9. (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:

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

  2. Click Next and specify authentication options on the Authentication page.

    For more information about authentication options, see Adding Authentication and Authorization to API Deployments.

  3. Click Next to enter details for individual routes in the API deployment on the Routes page.

  4. On the Routes page, select the route for which you want to specify header transformation response policies.
  5. Click Show Route Response Policies.
  6. Click the Add button beside Header Transformations to update the headers included in a response from the API gateway for the current route.

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

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

  9. 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.
  10. Click Save Changes, and then click Next to review the details you entered for individual routes.
  11. Click Create or Save Changes to create or update the API deployment.
  12. (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:

  1. 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"
      }
    }
  ]
}

  2. Insert a responsePolicies section after the backend 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": {}
    }
  ]
}

  3. Add a headerTransformations section to the responsePolicies section.

    {
  "routes": [
    {
      "path": "/hello",
      "methods": ["GET"],
      "backend": {
        "type": "ORACLE_FUNCTIONS_BACKEND",
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
      },
      "responsePolicies": {
        "headerTransformations":{}
      }
    }
  ]
}

  4. 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).
    • "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 in ALLOW 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.

  5. 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 in ALLOW 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 to X-User-ID, whilst keeping the header's original value.

  6. 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 in ALLOW 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.

    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 an X-Api-Key header set to a different value, the API gateway replaces the existing value with zyx987wvu654tsu321.

  7. Save the JSON file containing the API deployment specification.

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

  9. (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