HTTP Reference

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

Quick reference for HTTP methods, headers, content types, and protocol details used with Google Cloud APIs.

HTTP Methods

Method	Safe	Idempotent	Request Body	Use
GET	Yes	Yes	No	Retrieve a resource or list
POST	No	No	Yes	Create a resource or custom method
PUT	No	Yes	Yes	Full resource replacement
PATCH	No	No	Yes	Partial resource update
DELETE	No	Yes	No	Remove a resource

Safe: Does not modify server state. Idempotent: Multiple identical requests have the same effect as a single request.

Request Headers

Header	Value	Required	Purpose
Authorization	Bearer ACCESS_TOKEN	Yes (most APIs)	Authentication
Content-Type	application/json	Yes (POST/PUT/PATCH)	Request body format
Accept	application/json	Optional	Response format
X-HTTP-Method-Override	GET	When needed	Override POST to GET (long URLs)
x-goog-request-params	routing params	Auto (gRPC)	Request routing
x-goog-user-project	PROJECT_ID	Optional	Billing project override

Long URL Workaround

When a URL exceeds 16KB (e.g., complex filters), use POST with method override:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "X-HTTP-Method-Override: GET" \
  -d '{"filter": "very long filter expression..."}' \
  "https://SERVICE.googleapis.com/v1/RESOURCE"

Content Types

Content Type	Use
application/json	Standard REST/JSON (most common)
application/x-protobuf	Protocol Buffers binary
multipart/related	File uploads with metadata
application/octet-stream	Raw binary data

Response Format

Success (200/201):

{
  "name": "projects/my-project/topics/my-topic",
  "labels": {},
  "messageStoragePolicy": {},
  "schemaSettings": {}
}

Error (4xx/5xx):

{
  "error": {
    "code": 403,
    "status": "PERMISSION_DENIED",
    "message": "The caller does not have permission",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "IAM_PERMISSION_DENIED",
        "domain": "googleapis.com",
        "metadata": {
          "permission": "pubsub.topics.create"
        }
      }
    ]
  }
}

HTTP Versions

Version	Features	GCP Support
HTTP/1.1	Standard, text-based	Full
HTTP/2	Multiplexing, header compression, server push	Full (default for gRPC)
HTTP/3 (QUIC)	UDP-based, lower latency	Available on some services

Streaming

Type	Description	Use Case
Server-side streaming	Server sends multiple responses	Long-running reads, log tailing
Client-side streaming	Client sends multiple requests	Bulk uploads
Bidirectional streaming	Both sides stream simultaneously	Real-time communication

TIP

REST/JSON APIs support server-side streaming. Full bidirectional streaming requires gRPC.

URL Structure

https://{service}.googleapis.com/{version}/{resource_name}?{query_params}

Examples:

Service	URL
Cloud Storage	https://storage.googleapis.com/storage/v1/b/my-bucket
Pub/Sub	https://pubsub.googleapis.com/v1/projects/my-project/topics/my-topic
BigQuery	https://bigquery.googleapis.com/bigquery/v2/projects/my-project/datasets
Compute Engine	https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instances

Common Query Parameters

Parameter	Type	Use
pageSize	int	Max results per page
pageToken	string	Pagination cursor
filter	string	Result filtering
orderBy	string	Sort order
fields	string	Partial response (field mask)
key	string	API key authentication
alt	string	Response format (json, media, proto)

Partial Responses

Reduce response size by requesting only specific fields:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/storage/v1/b/my-bucket?fields=name,location,storageClass"

See Also

• Standard Methods -- How HTTP methods map to API operations
• Error Codes -- HTTP error code details
• HTTP Guidelines Guide -- Deep dive into HTTP protocol