Configuring Cloud Endpoints

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

Prerequisites

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

• A Google Cloud project .
• Basic knowledge of configuring a gRPC API service .
• Installed gRPC and the gRPC tools. Read Get started with gRPC for details.

Choosing the service name

The name of your API service must be unique on Google Cloud. Because 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 on the Endpoints Servicespage matches the name used in requests to your API. Endpoints has the following requirements for the service name:

• The maximum length of the domain name is 253 characters.
• The domain name must start with a lowercase letter.
• Each section in the domain name, which is delimited by dots, has the following requirements:
  • Must start with a lowercase letter.
  • Must not end with a dash.
  • The remaining characters can be lowercase letters, numbers, or dashes.
  • The maximum length is 63 characters.

You can either register your own custom domain (such as example.com ), or you can use a domain managed by Google.

Use a domain managed by Google

 YOUR_API_NAME 
.endpoints. YOUR_PROJECT_ID 
.cloud.goog`

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

Use 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. Read the Developer guide
   for details.

2. Compile your protocol buffers by 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 preceding 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 access your gRPC service by using HTTP with JSON, you need to specify how data is translated from HTTP with JSON to gRPC. We recommend that you annotate the APIs defined in your .proto file. Read 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 is displayed on the Endpoints> Servicespage in the Google Cloud console. 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. 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 
    
   

   Read Rules and selectors for more information.

What's next

• Deploying the Endpoints configuration
• Deploying the API backend
• Configuring authentication

Additional gRPC samples

• Java version of the Bookstore sample .

• The getting-started-grpc sample is available on GitHub in the following languages:

  • Java
  • Python
  • Ruby
  • Go
  • Node.js