Planning your Cloud Projects

This page provides recommendations for naming conventions of the Cloud projects that you may need to create in addition to the Cloud project for your production backend.

If you aren't using a custom domain name, as a best practice, we recommend the following naming pattern for your Cloud Endpoints service name:

API-NAME.endpoints.PROJECT-ID.cloud.goog

For example: my-api.endpoints.my‐project.cloud.goog

By using this naming pattern you can easily configure DNS for your Cloud Endpoints API. This way, the service name and the fully qualified domain name (FQDN) for the service are the same. See Configuring Endpoints DNS: OpenAPI and Configuring Endpoints DNS: gRPC for more information.

The exception to this recommendation is when you are using Google App Engine as a backend. When using App Engine, a DNS entry with the name PROJECT-ID.appspot.com is automatically created for your service. Although you can certainly use the *.cloud.goog naming pattern, you may prefer the naming pattern PROJECT-ID.appspot.com so that the service name and the FQDN are the same.

Depending on the purpose of the environment or the stage in the API lifecycle, you may want to:

  • Change the API name.
  • Create a different project.
  • Change the path that the API is served from.

Following are some common patterns you may want to use:

  • Versioning the API: When you think you may need to make backwards-incompatible changes in the future, plan ahead and add the version number in the path where the API is served from. For example:

    • my-api.endpoints.my‐project.cloud.goog/v1/echo

    See Versioning an API for more information.

  • Development/test instances: Each developer stands up their own version of the service, in their own project. For example, Dan the developer uses:

    • my-api.endpoints.dan-dev-project.cloud.goog/v1/echo
  • Staging: Before you deploy to production, you test your APIs on your staging backend, which is in its own project. For example:

    • my-api.endpoints.my‐project-staging.cloud.goog/v1/echo

    See API lifecycle management for more information.

  • Running a private alpha: When you want to test a new version of your service with some customers, but not all, the easiest approach is to put the alpha version in its own project, which provides the highest level of isolation from production. For example:

    • my-api.endpoints.my‐project-alpha.cloud.goog/v2alpha/echo

    Alternatively, you could put the alpha version in the same project but configure it as a separate service. Since it is a separate service, you can restrict access to only the alpha customers. For example:

    • my-api-alpha.endpoints.my-project.cloud.goog/v2alpha/echo
  • Running an open alpha: When you want to release an alpha version that is available to all customers, you can put it in the same service and project as the existing version, and change the path. For example:

    • my-api.endpoints.my-project.cloud.goog/v2alpha/echo

See also:

Send feedback about...

Cloud Endpoints with gRPC