OpenAPI 2.0 feature limitations

The following sections describe the limitations of OpenAPI 2.0 features on Endpoints.

Scopes ignored

Although Endpoints accepts OpenAPI documents that have scopes defined in a security scheme object, when a request is sent to your API, neither the Extensible Service Proxy (ESP), Extensible Service Proxy V2 (ESPv2), nor Cloud Endpoints Frameworks check the defined scopes.

Multiple security requirements

You can specify more than one security requirement in your OpenAPI document. This section describes the security schemes that ESP and ESPv2 support.

Security requirements containing an API key

ESP and ESPv2 don't support alternative (logical OR) security requirements when one of the security schemes is an API key. For example, ESP and ESPv2 don't support the following security requirement list:

security:
- petstore_auth: []
- api_key: []

This definition requires an operation to accept requests that follow the petstore_auth requirements or the api_key requirements.

Note, however, that ESP and ESPv2 support security requirement conjunctions (logical AND), so you can require both an API key and OAuth2 authentication. For example, the following security requirement list is supported:

security:
- petstore_auth: []
  api_key: []

This definition requires an operation to accept requests that simultaneously follow the petstore_auth requirements and the api_key requirements.

Security requirements for OAuth2

ESP and ESPv2 support security alternative (logical OR) security requirements, but only for OAuth2 authentication security schemes. For example, the following security requirement list is supported:

security:
  - firebase1: []
  - firebase2: []

Security definition validation

ESP and ESPv2 don't validate that all the security requirements (either at the API level or method level), also are present under the securityDefinitions section. As a result, if the API specification uses an undefined security schema, unauthenticated requests may come through the API, on the level where the undefined security key is configured. Make sure that all security keys used by your API and its methods are defined under the security definitions in your OpenAPI document.

URL path templating

Endpoints only supports URL path template parameters that correspond to entire path segments (delimited by slashes /). URL path template parameters that correspond to partial path segments aren't supported.

For example, the following URL path templates are supported:

• /items/{itemId}
• /items/{itemId}/subitems

The following URL path templates aren't supported and will be rejected:

• /items/overview.{format}
• /items/prefix_{id}_suffix

Operations on URL root path /

Endpoints accepts OpenAPI documents that include operations on the root path /. However, requests on the root path are rejected by ESP. Note, this limitation is only for ESP, ESPv2 supports root path /.

For example, the following OpenAPI document snippet is accepted:

paths:
  /:
    post:
      operationId: "root"
      responses:
        200:
          description: "Success"
          schema:
            type: string

But subsequent requests for POST / are rejected with the following error:

{
   "code": 5,
   "details": [
       {
           "@type": "type.googleapis.com/google.rpc.DebugInfo",
           "detail": "service_control",
           "stackEntries": []
       }
   ],
   "message": "Method does not exist."
}

File upload

Endpoints does not accept the type: file for file upload parameters, type: string should be used instead.

For example, the following type: file snippet is not allowed:

paths:
  /upload:
    post:
      summary: Uploads a file.
      consumes: