Get to Know Pub/Sub API
Learning Objectives
After completing this unit, you’ll be able to:
- Explain what you can use Pub/Sub API for.
- List the characteristics and features of Pub/Sub API.
Before You Begin
We know youre eager to get started! But before you settle in to work through this module, you should be familiar with the various types of real-time events. Check out these Trailhead modules to familiarize yourself with them.
What Is Pub/Sub API Used For?
With Pub/Sub API, you can write event-driven apps that integrate with Salesforce through real-time event messages, including platform events, change data capture events, and real-time event monitoring events. Based on gRPC and HTTP/2, Pub/Sub API efficiently publishes and delivers binary event messages in the Apache Avro format.
Here are some of the things you can do with Pub/Sub API.
- Publish and subscribe to custom platform events to send and receive real-time notifications in another system for business process integration. Some examples of business process integration are sending real-time notifications for maintenance service or product orders.
- Subscribe to change data capture events, and synchronize order data in an external inventory system.
- Subscribe to real-time event monitoring events to monitor security-related user actions in Salesforce in real time. For example, real-time event monitoring events can track when users log in to Salesforce, query sensitive data, or run reports.
- Subscribe to a standard platform event, such as AppointmentSchedulingEvent, and integrate with Google Calendar to update users’ calendars.
Pub/Sub API Characteristics and Features
Here are some of the features of Pub/Sub API.
Lean Data Transfer with Binary Event Messages and HTTP/2
Pub/Sub API is based on gRPC, a robust open-source RPC (remote procedure call) framework used to build scalable and fast APIs. Because Pub/Sub API is based on gRPC and HTTP/2, it benefits from HTTP/2 compression. With compression, the data transferred over HTTP/2 is smaller in size. As a result, publishing and subscribing to event messages is more efficient than using other APIs.
Also, Pub/Sub API publishes and delivers binary-encoded events with payloads encoded in the Apache Avro schema. Apache Avro is a data serialization system that provides a binary or JSON data encoding and a schema. The binary encoding is more efficient than the JSON encoding because it enables faster serialization and produces smaller sizes of serialized data.
The Pub/Sub API service is defined in the Pub/Sub API proto file. For more information, see Pub/Sub API as a gRPC API in the Pub/Sub API Guide.
Single API for Many Operations
Pub/Sub API provides a single interface for performing various operations, including:
- Publishing events
- Subscribing to events
- Getting the event schema
Increased Performance Through Bidirectional Streaming
With bidirectional streaming, the client and the Pub/Sub API service can send a sequence of messages to each other using two independent streams.
These RPC methods use bidirectional streaming:
PublishStreamSubscribeManagedSubscribe
This diagram shows how the request and response streams are two independent streams. A client uses one stream to send requests while the server uses the second stream to send responses.
For example, the PublishStream RPC method can send a stream of publish requests while receiving a stream of publish responses from the server. It achieves a higher publish rate than the Publish unary RPC. The server returns a PublishResponse for each PublishRequest when publishing is complete for the batch. It isn’t necessary for a client to wait for a PublishResponse before sending a new PublishRequest. Multiple publish batches can be queued up. This behavior allows for a higher publish rate because a client can asynchronously publish more events while publish operations are still in flight on the server side. We cover the differences of these two methods in more detail and when to use each in another unit later in this module.
Similarly, the Subscribe and ManagedSubscribe RPC methods can send a stream of FetchRequests or ManagedFetchRequests while receiving a stream of FetchResponses or ManagedFetchResponses from the server. It isn't necessary for the client to wait for a response to be returned before sending a new request for fetching more events. This behavior enables various subscription flows–more on that in a minute, in the Pull-Based Subscription and Flow Control section.
Final Publish Acknowledgements
When publishing events with Publish or PublishStream RPC methods, Pub/Sub API waits until the system stores the events in the event bus and returns the publishing result. The PublishResponse that the Publish or PublishStream RPC methods return holds the final result of the publishing. After the PublishResponse is returned, the publishing is complete in the event bus and there are no asynchronous processes lingering. A PublishResult is returned for each event published. It indicates success or failure of the publish operation. A successful result means that the event was published and is stored in the event bus. A failed result means that the event failed to publish and isn’t stored in the event bus.
In contrast, publishing events using other methods, like REST API or Apex, doesn't provide the final result. The result returned using those methods is only the intermediate queueing result before the system asynchronously publishes queued events internally. With Pub/Sub API, you can be confident that the event publishing result is final.
Pull-Based Subscription and Flow Control
Pull-based subscription enables the client to control the flow of events received so that it can receive only the volume of events it can process. This event flow control ensures that the client doesn’t get overwhelmed with more events than it can handle if there’s a spike in event publishing.
Using the Subscribe RPC and the ManagedSubscribe RPC methods, the client requests the number of events it is ready to receive from the server. To request events, the client sends a request with the number of events desired, up to a maximum of 100, and receives a response with the full or partial batch of events.
This diagram shows the flow of one fetch request sent asking for 100 events. The server responds back with three responses, each containing a partial number of events requested. Then the client asks for more events by sending another fetch request.
For more client flows, see Pull Subscription and Flow Control in the Pub/Sub API Guide.
In this unit, you learned about the main features of Pub/Sub API. Next, you dive into the managed subscriptions (beta) feature!