Guides

Task-oriented walkthroughs of common use cases

This document introduces you to gRPC and protocol buffers. gRPC can useprotocol buffers as both its Interface Definition Language (IDL) and as its underlying messageinterchange format. If you’re new to gRPC and/or protocol buffers, read this!If you just want to dive in and see gRPC in action first,see ourQuick Starts.

Overview

In gRPC, a client application can directly call a method on a server applicationon a different machine as if it were a local object, making it easier for you tocreate distributed applications and services. As in many RPC systems, gRPC isbased around the idea of defining a service, specifying the methods that can becalled remotely with their parameters and return types. On the server side, theserver implements this interface and runs a gRPC server to handle client calls.On the client side, the client has a stub (referred to as just a client in somelanguages) that provides the same methods as the server.

gRPC clients and servers can run and talk to each other in a variety of environments - from servers inside Google to your own desktop - and can be written in any of gRPC’s supported languages. So, for example, you can easily create a gRPC server in Java with clients in Go, Python, or Ruby. In addition, the latest Google APIs will have gRPC versions of their interfaces, letting you easily build Google functionality into your applications.

Working with Protocol Buffers

By default, gRPC usesProtocol Buffers, Google’smature open source mechanism for serializing structured data (although itcan be used with other data formats such as JSON). Here’s a quick intro to howit works. If you’re already familiar with protocol buffers, feel free to skipahead to the next section.

The first step when working with protocol buffers is to define the structurefor the data you want to serialize in a proto file: this is an ordinary textfile with a .proto extension. Protocol buffer data is structured asmessages, where each message is a small logical record of informationcontaining a series of name-value pairs called fields. Here’s a simpleexample:

message Person {
  string name = 1;
  int32 id = 2;
  bool has_ponycopter = 3;
}

Then, once you’ve specified your data structures, you use the protocol buffercompiler protoc to generate data access classes in your preferred language(s)from your proto definition. These provide simple accessors for each field,like name() and set_name(), as well as methods to serialize/parsethe whole structure to/from raw bytes. So, for instance, if your chosenlanguage is C++, running the compiler on the example above will generate aclass called Person. You can then use this class in your application topopulate, serialize, and retrieve Person protocol buffer messages.

You define gRPC servicesin ordinary proto files, with RPC method parameters and return types specified asprotocol buffer messages:

// The greeter 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;
}

gRPC uses protoc with a special gRPC plugin togenerate code from your proto file: you getgenerated gRPC client and server code, as well as the regular protocol buffercode for populating, serializing, and retrieving your message types. You’llsee an example of this below.

To learn more about protocol buffers, including how to install protoc with thegRPC plugin in your chosen language, see theprotocol buffers documentation.

Protocol buffer versions

Whileprotocol buffers have been available to open source users for some time,most examples from this site use protocol buffers version 3 (proto3), which hasa slightly simplified syntax, some useful new features, and supports morelanguages. Proto3 is currently available in Java, C++, Dart, Python,Objective-C, C#, a lite-runtime (Android Java), Ruby, and JavaScript from theprotocol buffers GitHub repo, as well as a Go language generator from thegolang/protobuf GitHub repo, with more languages in development. You canfind out more in theproto3 language guide and thereferencedocumentation available for each language. The reference documentation alsoincludes aformal specification for the .proto file format.

In general, while you can use proto2 (the current default protocol buffersversion), we recommend that you use proto3 with gRPC as it lets you use thefull range of gRPC-supported languages, as well as avoiding compatibilityissues with proto2 clients talking to proto3 servers and vice versa.