gRPC overview

gRPC is a high performance, open-source universal RPC framework, developed by Google. In gRPC, a client application can directly call methods on a server application on a different machine as if it was a local object, making it easier to create distributed applications and services.

One of the primary benefits of using gRPC is for documentation; you can use your service configuration and API interface definition files to generate reference documentation for your API.

API management

With API Gateway for gRPC, you can use the API management capabilities of API Gateway to add monitoring, hosting, tracing, authentication, and more to your gRPC services on Cloud Run. In addition, once you specify special mapping rules, API Gateway translates RESTful JSON over HTTP into gRPC requests. This means that you can deploy a gRPC server managed by API Gateway and call its API using a gRPC or JSON/HTTP client, giving you much more flexibility and ease of integration with other systems.

You can create gRPC services for API Gateway in any gRPC-supported language. You can find out much more about gRPC, including quickstarts and tutorials for creating servers and clients, on the gRPC site.

Service definition and configuration

gRPC is based on the idea of defining a service, specifying the methods that can be called remotely with their parameters and return types. By default, gRPC uses protocol buffers as the Interface Definition Language (IDL) for describing both the service interface and the structure of the payload messages.

// The greeting service definition.
service Greeter {
  // Sends a greeting
  rpc SayHello (HelloRequest) returns (HelloReply) {}
}

// The request message containing the user's name.
message HelloRequest {
  string name = 1;
}

// The response message containing the greetings
message HelloReply {
  string message = 1;
}

To use gRPC with API Gateway, you must provide a service configuration along with the service definition. This configures the runtime behavior of your service, including authentication, the API(s) included in the service, mappings from HTTP requests to gRPC methods, and special API Gateway settings.

Transcoding

API Gateway provides protocol translation for your gRPC services on Cloud Run allowing clients to use HTTP/JSON to communicate with a gRPC service through the API Gateway.

The most common use case is allowing browser clients to talk to gRPC servers without special support from gRPC client libraries. API Gateway provides a mechanism for mapping HTTP requests to gRPC methods as part of service configuration.

You can find out more about this in Transcoding HTTP/JSON to gRPC.

Note: When using gRPC transcoding, request and response body sizes exceeding one megabyte may result in 500 Internal Server Error responses.

If this size is exceeded, request logs for API Gateway will show grpc_json_transcode_failure{request_buffer_size_limit_reached} or grpc_json_transcode_failure{response_buffer_size_limit_reached} in the responseDetails field.

Limitations

The following gRPC features are not yet supported in API Gateway:

• Payload compression
• Any IDL other than protocol buffers

API Gateway only supports Cloud Run gRPC services at this time.

What's next

• Explore samples. The getting-started-grpc sample is available on GitHub in the following languages:
  • Java
  • Python
  • Ruby
  • Go
  • Node.js
• The Bookstore sample is available in the following languages:
  • Python
  • Java