Console
    Start free

    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
    Create a Mobile Website
    View Site in Mobile | Classic
    Share by: