OpenAPI 3.x Extensions in API Gateway

API Gateway accepts a set of Google-specific extensions to the OpenAPI specification that configure the behaviors of the gateway. These extensions allow you to specify API management settings, authentication methods, quota limits, and backend integrations directly within your OpenAPI document. Understanding these extensions helps you tailor your service behavior and integrate with API Gateway features.

This page describes Google-specific extensions to the OpenAPI specification 3.x.

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

x-google-api-management

Required.

The x-google-api-management extension defines top-level API management settings for your service. Place this extension at the root of your OpenAPI document.

The following table describes the fields for x-google-api-management:

Field Type Required Default Description
metrics map[string]Metric No Empty Define metrics to enforce quota limits.
quota map[string]Quota No Empty Specify quota limits for your service.
backends map[string]Backend Yes Empty Configure backend services.
apiName string No Empty Associate a name with the operations defined in the OpenAPI document.

Metric Object

The Metric object defines a metric used for quota enforcement.

The following table describes the fields for Metric:

Field Type Required Default Description
displayName string No Empty Display name of the metric.

Quota Object

The Quota object defines quota limits.

The following table describes the fields for Quota:

Field Type Required Default Description
limits map[string]QuotaLimit No Empty Specify quota limits.

Quota Limit Object

The QuotaLimit object defines a specific quota limit.

The following table describes the fields for QuotaLimit:

Field Type Required Description
metric string Yes Reference a metric declared in this OpenAPI document.
values int64 Yes Set the maximum value the metric can reach before client requests are denied.

Backend Object

The Backend object configures a backend service. You must set either jwtAudience or disableAuth.

The following table describes the fields for Backend:

Field Type Required Default Description
address string No Empty Specify the URL of the backend.
jwtAudience string No Empty By default, API Gateway will create the instance ID token with a JWT audience that matches the address field. Manually specifying jwt_audience is only required when the target backend uses JWT-based authentication and the expected audience is different than the value specified in the address field. For remote backends deployed on App Engine or with IAP, you must override the JWT audience. App Engine and IAP use their OAuth client ID as the expected audience.
disableAuth bool No False Prevent the data plane proxy from obtaining an instance ID token and attaching it to the request.
pathTranslation string No APPEND_PATH_TO_ADDRESS or CONSTANT_ADDRESS Set the path translation strategy when proxying requests to the target backend. When x-google-backend is set at the top level and no path_translation is specified, the default pathTranslation is APPEND_PATH_TO_ADDRESS. When x-google-backend is set on at the operation level and no path_translation is specified, the default is CONSTANT_ADDRESS.
deadline double No 15.0 Specify the number of seconds to wait for a full response from a request. Responses that exceed this deadline time out.
protocol string No http/1.1 Set the protocol for sending a request to the backend. Supported values include http/1.1 and h2.

x-google-auth

Optional.

The x-google-auth extension defines authentication settings within a Security Scheme Object.

The following table describes the fields for x-google-auth:

Field Type Required Default Description
issuer string No Empty Specify the issuer of a credential. Values can be a hostname or email address.
jwksUri string No Empty

Provide the URI of the provider's public key set to validate the signature of the JSON Web Token. API Gateway supports two asymmetric public key formats defined by this OpenAPI extension:

  1. JWK set format. For example: jwksUri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"
  2. X509. For example: jwksUri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"

If you are using a symmetric key format, set the jwksUri to the URI of a file that contains the base64url-encoded key string.
audiences [string] No Empty List audiences that the JWT aud field must match during JWT authentication.
jwtLocations [JwtLocations] No Empty Customize locations for the JWT token. By default, a JWT passes in the Authorization header (prefixed by "Bearer "), X-Goog-Iap-Jwt-Assertion header, or the access_token query parameter.

JwtLocations Object

The JwtLocations object provides customized locations for the JWT token.

The following table describes the fields for JwtLocations:

Field Type Required Default Description
header | query string Yes N/A Specify the name for the header containing the JWT, or the name for the query parameter containing the JWT.
valuePrefix string No Empty For header only. When set, its value must match the prefix of the header value containing the JWT.

x-google-quota

Optional.

The x-google-quota extension defines quota limits. You can define this extension at the top-level of your OpenAPI document or for an individual operation.

The following table describes the fields for x-google-quota:

Field Type Required Description
self map[string]int64 Yes The quota object (self) references any metrics defined within the object. In this case, map a metric (such as read-requests) to an amount to increment the metric. Requests are rejected when the metric value meets the quota limit.

x-google-backend

Required.

The x-google-backend extension references a backend defined in x-google-api-management. You must set this extension for API Gateway. You can define this extension at the top-level of your OpenAPI document or for an individual operation.

The following table describes the fields for x-google-backend:

Field Type Required Description
self string Yes Reference the ID of a backend defined in x-google-api-management.

x-google-endpoint

Optional.

The x-google-endpoint extension is used to configure the properties of a server defined in the servers array of an OpenAPI 3.x document. Only one server entry in your OpenAPI document can use the x-google-endpoint extension.

The extension also defines other backend features, including:

  • CORS: You can enable Cross-Origin Resource Sharing (CORS) by setting the allowCors property to true.

  • Base path: The base path set on the server with x-google-endpoint is used for your API. For example, the following configuration sets v1 as the base path:

servers:
  - url: https://API_NAME.apigateway.PROJECT_ID.cloud.goog/v1
    x-google-endpoint: {}

The following table describes the fields for x-google-endpoint:

Field Type Required Default Description
allowCors bool No false Allow CORS requests.

x-google-parameter

Optional.

The x-google-parameter extension is defined on a parameter item. This can be used when the path uses path templating to specify that double wildcard matching behavior should be used.

The following table describes the fields for x-google-parameter:

Field Type Required Description
pattern string Yes This must be set to **.

Understand OpenAPI Extension Limitations

These OpenAPI extensions have specific limitations. To learn more, see OpenAPI 3.x feature limitations.

What's next