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.

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 exactly 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."

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

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"

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