Updated 2024-10-03

Limiting the Number of Requests to API Gateway Back Ends

Find out how to use a request policy to limit the number of requests sent to back-end services with API Gateway.

Having created an API gateway and deployed one or more APIs on it, you'll typically want to limit the rate at which API clients can make requests to back-end services. For example, to:

  • maintain high availability and fair use of resources by protecting back ends from being overwhelmed by too many requests
  • prevent denial-of-service attacks
  • constrain costs of resource consumption
  • restrict usage of APIs by your customers' users in order to monetize APIs

You apply a rate limit globally to all routes in an API deployment specification.

If a request is denied because the rate limit has been exceeded, the response header specifies when the request can be retried.

You use a request policy to limit the number of requests (see Adding Request Policies and Response Policies to API Deployment Specifications).

You can add a rate-limiting request policy to an API deployment specification by:

  • using the Console
  • editing a JSON file

Using the Console to Add Rate-Limiting Request Policies

To add a rate-limiting request policy 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. In the API Request Policies section of the Basic Information page, click the Add button beside Rate Limiting and specify:

    • Number of Requests per Second: The maximum number of requests per second to send to the API deployment.
    • Type of Rate Limit: How the maximum number of requests per second threshold is applied. You can specify that the maximum applies either to the number of requests sent from any one API client (identified by its IP address), or to the total number of requests sent from all API clients.
  3. Click Save Changes.

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

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

  5. Click Next to enter details for individual routes in the API deployment on the Routes page. Note that you cannot apply rate-limiting policies to individual routes in the API deployment specification.

  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 Rate-Limiting Request Policies

To add a rate-limiting request policy 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 limit, 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 before the routes section, if one doesn't exist already. For example:

    {
      "requestPolicies": {},													
      "routes": [
        {
          "path": "/hello",
          "methods": ["GET"],
          "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
          }
        }
      ]
    }
  3. Add the following rateLimiting policy to the new requestPolicies section to apply to all routes defined in the specification:

    {
      "requestPolicies": {
        "rateLimiting": {
          "rateKey": "<ratekey-value>",
          "rateInRequestsPerSecond": <requests-per-second>
        }
      },													
      "routes": [
        {
          "path": "/hello",
          "methods": ["GET"],
          "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
          }
        }
      ]
    }

    where:

    • <ratekey-value> specifies whether the maximum number of requests threshold applies to the number of requests from individual API clients (each identified by their IP address) or to the total number of requests sent to the back-end service. Valid values are CLIENT_IP and TOTAL.
    • <requests-per-second> is the maximum number of requests per second to send to the API deployment.

    For example:

    {
      "requestPolicies": {
        "rateLimiting": {
          "rateKey": "CLIENT_IP",
          "rateInRequestsPerSecond": 10
        }
      },													
      "routes": [
        {
          "path": "/hello",
          "methods": ["GET"],
          "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
          }
        }
      ]
    }
  4. Save the JSON file containing the API deployment specification.
  5. 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.

  6. (Optional) Confirm the API has been deployed successfully by calling it (see Calling an API Deployed on an API Gateway).