Pub/Sub APIs overview

Stay organized with collections Save and categorize content based on your preferences.

Pub/Sub surfaces JSON/HTTP (commonly associated with RESTful systems) and gRPC interfaces.

If you don't want to use our client libraries to access the Pub/Sub API, you have the option of writing your own client libraries that use its REST or gRPC API surface. We recommend this approach only if your programming language or other needs are not met by the provided client libraries.

gRPC interface

You can generate your own gRPC client libraries in any gRPC-supported language for the Pub/Sub API from its .proto service definition using these resources:

• Pub/Sub service definition
• gRPC documentation: Everything you need to generate and use your own gRPC client code
• RPC API Reference: Language-independent overview of the RPC surface

JSON/HTTP interface

If you prefer working with the JSON/HTTP interface, you can use these resources:

• REST API Reference
• Guidelines for working with Google HTTP APIs
• API Discovery Service: Exposes machine readable metadata about the JSON/HTTP API surface, useful for creating client libraries, tools, and plugins.
• Directory of client samples built with JSON/HTTP APIs and the Google API Discovery Service.

Pub/Sub endpoints

An endpoint, in the context of publish-subscribe messaging systems such as Pub/Sub, refers to a location or address where a publisher client can publish messages or where a subscriber client can receive messages.

Pub/Sub has global and locational service endpoints.

• The global HTTP endpoint for JSON/HTTP is https://pubsub.googleapis.com.
• The global endpoint for gRPC is pubsub.googleapis.com:443.

Global endpoints

Requests to the global endpoint originating from within Google Cloud are routed to the Pub/Sub in the region where they originate. Examples of origins considered within Google Cloud include clients running on Compute Engine or App Engine. Requests to the global endpoint made over Interconnect are routed similarly to requests originating in the region associated with the interconnection. In case Pub/Sub becomes unavailable in a region, requests originating within the same Google Cloud region are not load balanced to a different region.

Requests sent to the global endpoint from outside of Google Cloud are routed to a nearby available region. The requests may be routed to a region with insufficient project quota for the request type. The region is also not guaranteed to be the closest geographically.

Locational endpoints

We recommend using locational endpoints as an alternative to the global one in the following cases:

• High volume applications running outside of Google Cloud that require sufficient quota in all regions where traffic might be routed.
• Applications where the publishers or subscribers run outside of Google Cloud and are not geographically close to each other. In such cases, you can reduce Google Cloud outbound message costs by configuring the applications outside of Google Cloud to use the locational endpoint corresponding to the region used by the application inside of Google Cloud. If both publishers and subscribers are outside of Google Cloud, configure them to use the same locational endpoint.
• Applications which require that data be processed in a specific region.
• When publishing with ordering.
• When subscribing with exactly-once delivery.

Set a locational endpoint override

You can set a locational endpoint override for any Pub/Sub operation that calls a Pub/Sub endpoint (JSON/HTTP or gRPC).

CLOUDSDK_API_ENDPOINT_OVERRIDES_PUBSUB=ENDPOINT_OVERRIDE \
gcloud pubsub topics publish TOPIC_ID \
--message=“MESSAGE_DATA”

export CLOUDSDK_API_ENDPOINT_OVERRIDES_PUBSUB=ENDPOINT_OVERRIDE

List of locational endpoints

To send requests directly to a region, use the following locational Pub/Sub endpoints: