OpenAPI Extensions

Cloud Endpoints accepts a set of Google-specific extensions to the OpenAPI specification that configure the behaviors of the Extensible Service Proxy and Google Service Control. This page describes Google- specific extensions to the OpenAPI specification.

Although the examples given below are in YAML format, JSON is also supported.

Naming Convention

Google OpenAPI extensions have names that begin with the x-google- prefix.

x-google-allow

x-google-allow: [configured | all]

This extension is used at the top level of an OpenAPI specification to indicate what URL paths should be allowed through Cloud Endpoints Extensible Service Proxy (the proxy).

Possible values are configured and all.

The default value is configured, which means that only the API methods that you have listed in your OpenAPI specification are served through the proxy.

When all is used, unconfigured calls—with or without an API key or user authentication—pass through the proxy to your API.

The proxy processes calls to your API in a case-sensitive manner. For example, the proxy considers /widgets and /Widgets as different API methods.

When all is used, you need to take extra care in two areas:

  • Any API key or authentication rules.
  • The backend path routing in your service.

As a best practice, we recommend that you configure your API to use case-sensitive path routing. By using case-sensitive routing, your API will return an HTTP status code of 404 when the method requested in the URL does not match the API method name listed in your OpenAPI specification. Note that web application frameworks such as Node.js Express have a setting to enable or disable case-sensitive routing. The default behavior depends on the framework that you are using. We recommend that you review the settings in your framework to make sure that case-sensitive routing is enabled. This recommendation agrees with the OpenAPI Specification v2.0 that says: "All field names in the specification are case sensitive."

Example

Assume that:

  • x-google-allow is set to all.
  • The API method widgets is listed in your OpenAPI specification but not Widgets.
  • You have configured your OpenAPI specification to require an API key.

Because widgets is listed in your OpenAPI specification, the proxy blocks the following request because it doesn't have an API key:

https://my-project-id.appspot.com/widgets

Because Widgets is not listed in your OpenAPI specification, the proxy passes the following request through to your service without an API key:

https://my-project-id.appspot.com/Widgets/

If your API uses case-sensitive routing (and you have not routed calls to "Widgets" to any code), your API backend will return a 404. If, however, you are using case-insensitive routing, your API backend will route this call to "widgets."

Different languages and frameworks have different methods for controlling case sensitivity and routing. Consult the documentation for your framework for details.

x-google-endpoints

x-google-endpoints:
  - name: "[API_NAME].endpoints.[PROJECT_ID].cloud.goog"
    target: "[IP_ADDRESS]"

This extension is used at the top level of your OpenAPI specification to configure a DNS A-record for Cloud Endpoints services using the domain name format .endpoints.[PROJECT_ID].cloud.goog. The .cloud.goog domain is managed by Google and shared by Google Cloud customers. Because Cloud Platform Console project IDs are guaranteed to have a globally unique name, a domain name in the format .endpoints.[PROJECT_ID].cloud.goog will be unique and can be used as the domain name in the URL for your API.

For example:

    swagger: "2.0"
    host: "my-cool-api.endpoints.my-project-id.cloud.goog"
    x-google-endpoints:
    - name: "my-cool-api.endpoints.my-project-id.cloud.goog"
      target: "192.0.2.1"

Typically, you will configure the host field and the x-google-endpoints.name field to be the same. When you deploy your OpenAPI specification, the text specified in the host field is used as the name of your Endpoints service.

x-google-issuer

x-google-issuer: [URI | EMAIL_ADDRESS]

This extension is used in the OpenAPI securityDefinitions section to specify the issuer of a credential. Values can take the form of a hostname or email address.

x-google-jwks_uri

x-google-jwks_uri: [URI]

URI of the provider's public key set to validate signature of the JSON Web Token.

x-google-audiences

x-google-audiences: STRING

This extension is used in the OpenAPI securityDefinitions section to provide a list of audiences the API accepts. This extension accepts a single string with values separated by a comma. Spaces are not allowed between the audiences.

These three extensions are illustrated in the following example:

securityDefinitions:
  google_id_token:
    type: oauth2
    authorizationUrl: ""
    flow: implicit
    x-google-issuer: "https://accounts.google.com"
    x-google-jwks_uri: "https://www.googleapis.com/oauth2/v1/certs"
    x-google-audiences: "848149964201.apps.googleusercontent.com,841077041629.apps.googleusercontent.com"

x-google-management

The x-google-management extension controls different aspects of API management and contains the fields described in this section.

metrics:

You use metrics in conjunction with quota and x-google-quota to configure a quota for your API. A quota lets you control the rate at which applications can call the methods in your API. For example:

x-google-management:
  metrics:
    - name: read-requests
      displayName: Read requests
      valueType: INT64
      metricKind: DELTA

The metrics field contains a list with the following key-value pairs:

Element Description
name Required. The name for this metric. Typically, this is the type of request (for example, "read-requests" or "write-requests") that uniquely identifies the metric.
displayName

Optional, but recommended. The text displayed to identify the metric on the Quotas page in the Endpoints dashboard. This text is also displayed to consumers of your API on the Quotas page of IAM & admin and API & services. The display name must be a maximum of 40 characters.

For readability purposes, the unit from the associated quota limit is automatically appended to the display name on the Quotas pages in Cloud Platform Console. For example, if you specify "Read requests" for the display name, then "Read requests per minute per project" is displayed on the Quotas pages. If not specified, "unlabeled quota" is displayed to the consumers of your API on the Quotas pages of IAM & admin and API & services.

To maintain consistency with the display names of Google services listed on the Quotas pages that consumers of your API see, we recommend the following for the display name:

  • Use "Requests" when you have only one metric.
  • When you have multiple metrics, each should describe the type of request and contain the word "requests" (for example "Read requests" or "Write requests").
  • Use "quota units" instead of "requests" when any of the costs associated with the metric is greater than 1.
valueType Required. Must be INT64
metricKind Required. Must be DELTA

quota:

You specify the quota limit for a defined metric in the quota section. For example:

quota:
  limits:
    - name: read-requests-limit
      metric: read-requests
      unit: 1/min/{project}
      values:
        STANDARD: 5000

The quota.limits field contains a list with the following key:value pairs:

Element Description
name Required. Name of the limit, which must be unique within the service The name can contain lower and upper case letters, numbers and `-` (the dash character), and it must have a maximum length of 64 characters.
metric Required. The name of the metric this limit applies to. This name must match the text specified in the name of a metric. If the specified text does not match a metric name, you will get an error when you deploy the OpenAPI configuration file.
unit Required. The unit of the limit. Currently only "1/min/{project}" is supported, which means that the limit is enforced per-project and the usage is reset every minute.
values Required. The limit for the metric. You must specify this as a key:value pair, in the following format:
STANDARD: [YOUR-LIMIT-FOR-THE-METRIC]
You replace [YOUR-LIMIT-FOR-THE-METRIC] with an integer value that is the maximum number of requests allowed for the specified unit (which is currently only per-minute, per-project). For example:
values:
  STANDARD: 5000

x-google-quota

The x-google-quota extension is used in the OpenAPI paths section to associate a method in your API with a metric. Methods that do not have x-google-quota defined do not have quota limits applied to them. For example:

x-google-quota:
  metricCosts:
    read-requests: 1

The x-google-quota extension contains the following item:

Element Description
metricCosts A user-defined key:value pair: "[YOUR-METRIC-NAME]": [METRIC-COST].
  • "[YOUR-METRIC-NAME]": The text for "[YOUR-METRIC-NAME"] must match a defined metric name.
  • [METRIC-COST]: An integer value that defines the cost for each request. When a request is made, the associated metric is incremented by the specified cost. The cost allows methods to consume at different rates from the same metric. For example, if a metric has a quota limit of 1000 and a cost of 1, the calling application can make 1000 requests per minute before going over the limit. With a cost of 2 for the same metric, a calling application can make only 500 requests per minute before going over the limit.

Quota Examples

The following example shows adding a metric and limit for read requests and write requests.

x-google-management:
  metrics:
    # Define a metric for read requests.
    - name: "read-requests"
      displayName: "Read requests"
      valueType: INT64
      metricKind: DELTA
    # Define a metric for write requests.
    - name: "write-requests"
      displayName: "Write requests"
      valueType: INT64
      metricKind: DELTA
  quota:
    limits:
      # Rate limit for read requests.
      - name: "read-requests-limit"
        metric: "read-requests"
        unit: "1/min/{project}"
        values:
          STANDARD: 5000
      # Rate limit for write requests.
      - name: "write-request-limit"
        metric: "write-requests"
        unit: "1/min/{project}"
        values:
          STANDARD: 5000

paths:
  "/echo":
    post:
      description: "Echo back a given message."
      operationId: "echo"
      produces:
      - "application/json"
      responses:
        200:
          description: "Echo"
          schema:
            $ref: "#/definitions/echoMessage"
      parameters:
      - description: "Message to echo"
        in: body
        name: message
        required: true
        schema:
          $ref: "#/definitions/echoMessage"
      x-google-quota:
        metricCosts:
          read-requests: 1
      security:
      - api_key: []

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Cloud Endpoints with OpenAPI