Adding Request Policies and Response Policies to API Deployment Specifications

You can control the behavior of an API deployment you create on an API gateway by adding request and response policies to the API deployment specification:

  • a request policy describes actions to be performed on an incoming request from an API client before it is sent to a back end
  • a response policy describes actions to be performed on a response returned from a back end before it is sent to an API client

You can use request policies and/or response policies to:

  • limit the number of requests sent to back-end services
  • enable CORS (Cross-Origin Resource Sharing) support
  • provide authentication and authorization
  • validate requests before sending them to back-end services
  • modify incoming requests and outgoing responses
  • cache responses to improve performance and reduce load on back-end services

You can add policies to an API deployment specification that apply globally to all routes in the API deployment specification, as well as policies that apply only to particular routes.

Note that API Gateway request policies and response policies are different to IAM policies, which control access to Oracle Cloud Infrastructure resources.

You can add request and response policies to an API deployment specification by:

  • using the Console
  • editing a JSON file

Using the Console to Add Request Policies and Response Policies

To add request policies and response policies to an API deployment specification using the Console:

  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 API Gateways and API Deployments.

  2. In the API Request Policies section of the Basic Information page, specify request policies that apply globally to all routes in the API deployment specification:

    • Authentication: A policy to control access to APIs you deploy to API gateways based on the end user sending a request, and define what it is that they are allowed to do. Having specified a global authentication policy first, you can then specify authorization policies that apply to individual routes in the API deployment specification. See Adding Authentication and Authorization to API Deployments.
    • CORS: A policy to enable CORS support in the APIs you deploy to API gateways. You can also specify CORS policies that apply to individual routes in the API deployment specification (you don't need to have entered a global CORS policy first). See Adding CORS support to API Deployments.
    • Rate Limiting: A policy to limit the rate at which API clients can make requests to back-end services. You can only apply a rate-limiting policy globally to all routes in the API deployment specification (not to individual routes). See Limiting the Number of Requests to API Gateway Back Ends.
  3. Click Next to enter details for individual routes in the API deployment on the Routes page.

  4. To specify request policies that apply to an individual route, click Show Route Request Policies and specify:

  5. To specify response policies that apply to an individual route, click Show Route Response Policies and specify:

  6. Click Next to review the details you entered for the API deployment.
  7. Click Create or Save Changes to create or update the API deployment.
  8. (Optional) Confirm the API has been deployed successfully by calling it (see Calling an API Deployed on an API Gateway).

Editing a JSON File to Add Request Policies and Response Policies

To add request policies and response policies to an API deployment specification in a JSON file:

  1. Using your preferred JSON editor, edit the existing API deployment specification to which you want to add a request policy or response policy, or create a new API deployment specification (see Creating an API Deployment Specification).

    At a minimum, the API deployment specification will include a routes section containing:

    • A path. For example, /hello
    • One or more methods. For example, GET
    • A definition of a back end. For example, a URL, or the OCID of a function in Oracle Functions.

    For example, the following basic API deployment specification defines a simple Hello World serverless function in Oracle Functions as a single back end:

    {
      "routes": [
        {
          "path": "/hello",
          "methods": ["GET"],
          "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
          }
        }
      ]
    }
  2. To add a request policy that applies globally to all routes in the API deployment specification:

    1. Insert a requestPolicies section before the routes section. For example:

      
      {
        "requestPolicies": {},
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
               "type": "ORACLE_FUNCTIONS_BACKEND",
               "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            }
          }
        ]
      }
    2. Include a request policy in the requestPolicies section.

      For example, to limit the number of requests sent to all routes in an API deployment specification, you'd include the rateLimiting policy in the requestPolicies section as follows:

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

      For more information about the rateLimiting request policy, see Limiting the Number of Requests to API Gateway Back Ends.

  3. To add a request policy that applies to an individual route in the API deployment specification:

    1. Insert a requestPolicies section after the route's backend section. For example:

      {
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            },
            "requestPolicies": {}
          }
        ]
      }
    2. Include a request policy in the requestPolicies section.

      For example, to enable CORS support in an API deployment for a particular route, you'd include the cors policy in the requestPolicies section as follows:

      {
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            },
            "requestPolicies": {
              "cors":{
                 "allowedOrigins": ["*", "https://oracle.com"],
                 "allowedMethods": ["*", "GET"],
                 "allowedHeaders": [],
                 "exposedHeaders": [],
                 "isAllowCredentialsEnabled": false,
                 "maxAgeInSeconds": 3000
              }
            }
          }
        ]
      }

      For more information about the cors request policy, see Adding CORS support to API Deployments.

  4. To add a response policy that applies to an individual route in the API deployment specification:

    1. Insert a responsePolicies section after the route's backend section. For example:

      {
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            },
            "responsePolicies": {}
          }
        ]
      }
    2. Include a response policy in the responsePolicies section.

      For example, to rename any X-Username header to X-User-ID in the response from a particular route, you'd include the headerTransformations policy in the responsePolicies section as follows:

      {
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            },
            "responsePolicies": {
              "headerTransformations": {
                "renameHeaders": {
                  "items": [
                    {
                      "from": "X-Username",
                      "to": "X-User-ID"
                    }
                  ]
                }
              }
            }
          }
        ]
      }

      For more information about the headerTransformations response policy, see Editing a JSON File to Add Header Transformation Response Policies.

  5. Save the JSON file containing the API deployment specification.
  6. 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.