HTTP Guidelines

✅ Fresh -- Updated March 2026 from official Google Cloud documentation.

Overview

Google Cloud APIs communicate over HTTP using JSON (REST) or Protocol Buffers (gRPC). This guide covers the protocol-level details, streaming patterns, and best practices.

HTTP Protocol Stack

REST vs. gRPC

Feature	REST (JSON/HTTP)	gRPC (Protobuf/HTTP/2)
Format	JSON text	Protobuf binary
Transport	HTTP/1.1 or HTTP/2	HTTP/2 only
Streaming	Server-side only	Full bidirectional
Browser support	Native	Requires grpc-web proxy
Code generation	Optional	Required (from .proto files)
Performance	Good	Better (binary, smaller payload)
Debugging	Easy (readable JSON)	Harder (binary format)
Client libraries	Always available	Always available

HTTP Semantics

Request Structure

METHOD /version/resource_name?query_params HTTP/1.1
Host: service.googleapis.com
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{request body}

Safe and Idempotent Methods

Method Behaviors

GET -- Retrieve a resource. Never changes server state. Can be cached.

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/storage/v1/b/my-bucket"

POST -- Create a resource or invoke a custom method. Not idempotent by default.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{"name": "projects/my-project/topics/my-topic"}' \
  "https://pubsub.googleapis.com/v1/projects/my-project/topics/my-topic"

PATCH -- Partial update. Only specified fields are modified.

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{"labels": {"env": "prod"}}' \
  "https://pubsub.googleapis.com/v1/projects/my-project/topics/my-topic?updateMask=labels"

DELETE -- Remove a resource. Idempotent (deleting twice has same effect).

curl -X DELETE \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://pubsub.googleapis.com/v1/projects/my-project/topics/my-topic"

Streaming

Server-Side Streaming

The server sends multiple response messages for a single request. Used for:

• Long-running reads
• Log tailing
• Large dataset downloads

# Example: Streaming query results from BigQuery
curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://bigquery.googleapis.com/bigquery/v2/projects/my-project/queries/JOB_ID?alt=media"

Full-Duplex Streaming (gRPC only)

Both client and server send streams of messages simultaneously. Used for:

• Real-time communication
• Speech-to-text streaming recognition
• Bidirectional data exchange

# Example: Streaming speech recognition
from google.cloud import speech_v1

client = speech_v1.SpeechClient()

# Stream audio data to the API
requests = generate_audio_requests()  # yields StreamingRecognizeRequest
responses = client.streaming_recognize(requests=requests)

for response in responses:
    for result in response.results:
        print(result.alternatives[0].transcript)

Half-Duplex Streaming

One side streams at a time (not simultaneous). The client sends all data first, then the server responds.

State Management

Cancellation

Clients can cancel in-flight requests:

• REST: Close the HTTP connection
• gRPC: Send a cancellation on the stream

Keep-Alive

HTTP/2 connections use PING frames for keep-alive. Client libraries handle this automatically.

Connection Pooling

Client libraries maintain connection pools to reduce latency:

• Reuse TCP connections
• Reuse TLS sessions
• Multiplex requests over HTTP/2

Flow Control

Client-Side

Strategy	Description
Rate limiting	Limit requests per second
Backpressure	Stop reading from stream when buffer is full
Pagination	Use page_size to control response volume

Server-Side

Strategy	Description
Quota	Per-project request limits
Rate limiting	Per-method request limits
Flow control frames	HTTP/2 WINDOW_UPDATE frames

Performance Best Practices

1. Use client libraries -- They handle connection pooling, retries, and auth automatically
2. Enable HTTP/2 -- Better performance from multiplexing and header compression
3. Use partial responses -- ?fields=name,status reduces payload size
4. Batch operations -- Use batch methods (e.g., batchGet) to reduce round trips
5. Cache responses -- Cache GET responses with appropriate TTLs
6. Use regional endpoints -- Minimize network latency
7. Compress payloads -- Use Accept-Encoding: gzip for large responses

# Example: Request gzip compression
curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Accept-Encoding: gzip" \
  "https://storage.googleapis.com/storage/v1/b?project=my-project" \
  --compressed

See Also

• HTTP Reference -- Quick lookup tables
• Standard Methods -- How HTTP maps to API methods
• Client Libraries Guide -- Using libraries that handle HTTP for you