Configuring Endpoints

This page describes the configuration files needed to create a gRPC service that will be managed by Cloud Endpoints.

Prerequisites

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

Choosing the service name

Cloud Endpoints uses the name you configure in your gRPC API configuration YAML file 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 domain. 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. If you want to use the cloud.goog domain, the service name must be in the 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.

Configuring the protocol buffer

  1. Create a .proto file for your service. See the Developer Guide in the gRPC Documentation for details.

  2. Compile your protocol buffers using the protoc compiler for your language. For example:

    protoc
      --proto_path=. \
      --include_imports \
      --include_source_info \
      --descriptor_set_out=api_descriptor.pb \
      bookstore.proto
    

In the above command, --proto_path is set to the current working directory. In your gRPC build environment, if you use a different directory for .proto input files, change --proto_path so the compiler searches the directory where you saved your .proto file.

If the protoc command to generate your descriptor file fails, make sure that:

  • Your protoc version is up-to-date.
  • You specified the --proto_path or its short form -I for the root directories for imported .proto files. You can find out more in the protocol buffers documentation.
  • You specified --include_imports.

If you want your clients to be able to access your gRPC service using HTTP with JSON, you will need to specify how data should be translated from HTTP/JSON to gRPC. We recommend that you annotate the APIs defined in your .proto file. See Transcoding HTTP/JSON to gRPC for more information.

Configuring the gRPC service configuration file

You need to create a gRPC service configuration YAML file. You specify the name of the service and usage restrictions such as requiring an API key in this file. You can use the api_config.yaml file from the Bookstore sample as a model.

  1. Save a copy of api_config.yaml.

  2. Enter the name of your service in the name field. For example:

    name: bookstore.endpoints.example-project-12345.cloud.goog
    
  3. Enter the title that will be displayed in the Endpoints dashboard. For example:

    title: Bookstore gRPC API
    
  4. Enter the API name in the apis:name field. The text that you enter must exactly match the fully-qualified API name from your .proto file; otherwise deploying the Endpoints configuration won't work. For example:

    apis:
      - name: endpoints.examples.bookstore.Bookstore
    
  5. Configure the rest of the file. For example:

    #
    # API usage restrictions.
    #
    usage:
      rules:
      # ListShelves methods can be called without an API Key.
      - selector: endpoints.examples.bookstore.Bookstore.ListShelves
        allow_unregistered_calls: true
    

    See Rules and selectors for more information.

What's next

Additional gRPC samples

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

Send feedback about...

Cloud Endpoints with gRPC