Configuring Endpoints

Cloud Endpoints supports APIs that are described using version 2.0 of the OpenAPI specification. You describe the API surface and configure Cloud Endpoints features such as authentication rules or quotas in an OpenAPI document.

Cloud Endpoints makes special use of the following required fields in your OpenAPI document:

  • host
  • info.title
  • info.version
  • operationId

This page provides information about how Cloud Endpoints uses the above fields. With this information, you can finish preparing your OpenAPI document for deployment.

Prerequisites

As a starting point, this page assumes that you have:

host

Cloud Endpoints uses the name you configure in the host field of your OpenAPI document as the name of your service.

The name of your API service must be unique on GCP. Because Cloud Endpoints uses DNS-compatible names to identify services, we recommend that you use your API's domain name or subdomain name as the service name. With this approach, the service name that appears in the Endpoints dashboard matches the name used in requests to your API.

You can either register your own domain (for example my-company.com), or you can use a domain managed by Google.

Using a domain managed by Google

Google owns and manages the cloud.goog and the appspot.com domains. If you want to use a domain managed by Google, you must use your GCP project ID as part of the service name. Because GCP Console projects are guaranteed to have a globally unique project ID, this requirement ensures that you have a unique service name.

The domain name that you use depends on the backend that will host your API:

  • For APIs that will be hosted on App Engine flexible environment, you must use the appspot.com domain, and the service name must be in the following format:

      YOUR_PROJECT_ID.appspot.com
    

    When you deploy your API to App Engine, a DNS entry with a name in the format YOUR_PROJECT_ID.appspot.com is created automatically.

  • For APIs that will be hosted on Compute Engine, Kubernetes Engine, or Kubernetes, you must use the cloud.goog domain, and the service name must be in the following format:

      YOUR_API_NAME.endpoints.YOUR_PROJECT_ID.cloud.goog
    

    To use this as the API's domain name, see Configuring DNS on the cloud.goog domain.

Using a custom domain

If you don't want to use a domain managed by Google, you can use a custom domain (for example, myapi.mycompany.com) that you are authorized to use. Before you deploy the API configuration, follow the steps in Verify ownership of the domain.

info.title

The Endpoints dashboard displays the text that your have configured in the info.title field as a user-friendly name for your API. If you have more than one API per GCP project, the API name is displayed in a list when you first open the dashboard. You can click on the API name to open another page that displays the API's metrics, deployment history, and other information.

info.version

The Endpoints dashboard displays the version number for you API. Before deploying your API configuration for the first time, we recommend that you:

  • Set the version number in the info.version field to the applicable API version. For example: 1.0

  • Set the basePath field to the major version number. For example: /v1

For additional information on versioning your API, see API Lifecycle Management.

operationId

Although the operationId is an optional field in the OpenAPI Specification, Cloud Endpoints requires this field because it is used for internal identification of the operation. The string that you use for the operationId must be unique within your API. See the description for operationId in the OpenAPI Specification for guidance on naming.

What's next

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Endpoints with OpenAPI