Configuring Quotas

This page describes how to configure quotas for your API. At a high level, the steps are:

  1. Add the information about the quota to your OpenAPI configuration file.
  2. Deploy your OpenAPI configuration file.
  3. Deploy the Extensible Service Proxy.

For an overview of the functionality provided by quotas, see About Quotas.

Prerequisites

As a starting point, this page assumes that you have:

Adding a quota to your OpenAPI document

The following procedure describes adding the required extensions to your OpenAPI document to set up quotas. For simplicity, this page refers to the OpenAPI document as openapi.yaml and provides the OpenAPI extensions only in YAML format.

You will add three sections to openapi.yaml:

  • x-google-management.metrics: A named metric that counts requests to your API. You provide a name that describes the counter. The name could be a category, such as read-requests or write-requests. Alternatively, if you are defining a quota for a specific method, you might want to include the method name, for example: echo-api/echo_requests

  • x-google-management.quota.limits: Represents a single enforceable limit on a named metric. This is where you configure the allowed number of requests for a metric that you have defined. Currently, only per-minute, per-project limits are supported.

  • x-google-quota.metricCosts: The metricCosts maps methods to metrics (many-to-many). A request to a method allocates a counter for each of the mapped metrics. When you associate a method with a metric, you always specify a cost for the request. You can configure the cost of each method independently. This allows different methods to consume at different rates from the same named metric. If you don't have a complex quota requirement, you can configure the cost of every metric to 1.

To configure quotas on your API:

  1. Open your project's openapi.yaml file in a text editor.
  2. If you don't already have it, add the x-google-management extension at the root of the file (not indented or nested) above where the paths are defined.
  3. Add the metrics definition indented under x-google-management.

    x-google-management:
      metrics:
        - name: "[YOUR-METRIC-NAME]"
          displayName: "[YOUR-METRIC-DISPLAY-NAME]"
          valueType: INT64
          metricKind: DELTA
    
    1. Replace [YOUR-METRIC-NAME] with a name that describes the API requests counter.
    2. Replace [YOUR-METRIC-DISPLAY-NAME] with the text that will be displayed in the Endpoints dashboard on the Quotas page to identify the metric.
    3. The valueType field must be INT64.
    4. The metricKind field must be DELTA.

  4. Add a quota field at the same level as metrics, and add a limits field nested within the quota section.

    quota:
      limits:
        - name: "[YOUR-LIMIT-NAME]"
          metric: "[YOUR-METRIC-NAME]"
          unit: "1/min/{project}"
          values:
            STANDARD: [VALUE-FOR-THE-LIMIT]
    
    1. Replace [YOUR-LIMIT-NAME] with a name that describes the limit.
    2. Replace [YOUR-METRIC-NAME] with a previously defined metric.name.
    3. The unit field must be "1/min/{project}". This is the identifier for the per-minute per-project limit.
    4. The values field must contain STANDARD.
    5. Replace [VALUE-FOR-THE-LIMIT] with an integer value. This is the number of requests that an application associated with a consumer's Cloud project can make in a minute.

  5. Optionally, define additional metrics and limits for each metric.

  6. In the paths section of openapi.yaml, add the x-google-quota extension indented under each method that you want to apply a quota to.

      x-google-quota:
        metricCosts:
          [YOUR-METRIC-NAME]: [YOUR-METRIC-COST]
    
    1. Replace [YOUR-METRIC-NAME] with a previously defined metric.name.
    2. Replace [YOUR-METRIC-COST] with an integer. For each request, the request counter for the metric is incremented by the number you specify for the cost.

  7. Save openapi.yaml.

See OpenAPI Extensions for more examples and detailed descriptions of the x-google-management and x-google-quota extensions.

Deploying openapi.yaml and the Extensible Service Proxy

For the quota to take effect, you must:

  1. Deploy openapi.yaml to Service Management, which updates the configuration in Cloud Endpoints.
  2. Deploy the Extensible Service proxy. The steps for deploying the Extensible Service Proxy vary by the backend that your API is deployed on.

For detailed steps, see Deploying the API Backend.

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Endpoints with OpenAPI