Pub/Sub API as a gRPC API

Because the Pub/Sub API is a gRPC API, let’s define what a gRPC API is. gRPC is an open source Remote Procedure Call (RPC) framework that enables connecting devices, mobile applications, and browsers to backend services. With gRPC, a client app can call a method on a server as if it were a local object, making it easier for you to create distributed apps and services.

gRPC requires defining a service, which specifies the methods that can be called remotely with their parameters and return types. The server implements this interface and runs a gRPC server to handle client calls. The client has a stub that mirrors the methods available on the server.

Pub/Sub API uses a secure gRPC channel to connect to the endpoint over SSL. For available endpoints, see Pub/Sub API Endpoints.

Pub/Sub API uses protocol buffers as the Interface Definition Language (IDL) and as the underlying message interchange format. The Pub/Sub API service is defined in a proto file, with RPC method parameters, such as FetchRequest, and return types, such as FetchResponse, specified as protocol buffer messages. Within those protocol buffer messages, the payload field of published and delivered events is encoded in binary Apache Avro. For example, ProducerEvent is the event that the Publish and PublishStream RPC methods publish as part of PublishRequest. The payload field of ProducerEvent is encoded in binary Apache Avro, but the other fields aren't. Similarly, ConsumerEvent is the type of event that is delivered to a Subscribe RPC method as part of FetchResponse. The payload field of ConsumerEvent is encoded in binary Apache Avro, but the other fields aren't. For more information about event serialization, see Event Data Serialization with Apache Avro.

This proto file example is based on the Pub/Sub API proto file, but we shortened it in the illustration. The proto file defines the service by listing the methods to publish, subscribe, get the schema, and get the topic information. For the full definition of the Pub/Sub API proto file, see Pub/Sub API proto file in GitHub.

This proto file excerpt lists the messages for the Subscribe method. FetchRequest is the request message of the Subscribe method. FetchResponse is the response message of the Subscribe method. For brevity, we omitted other messages in this example.