Standard Methods (AIP-130)

✅ Fresh -- Updated March 2026 from official Google Cloud API Design Guide.

Overview

Standard methods are the five fundamental CRUD operations that every resource-oriented API should support. They provide a consistent, predictable interface across all Google Cloud APIs.

The Five Standard Methods

Method	HTTP Mapping	Request Body	Response Body
Get	GET /v1/{name=resources/*}	None	Resource
List	GET /v1/{parent=parents/*}/resources	None	Resource list
Create	POST /v1/{parent=parents/*}/resources	Resource	Resource
Update	PATCH /v1/{name=resources/*}	Resource	Resource
Delete	DELETE /v1/{name=resources/*}	None	Empty or Resource

Get

Retrieves a single resource by name.

# Get a specific Pub/Sub topic
curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://pubsub.googleapis.com/v1/projects/my-project/topics/my-topic"

Key behaviors:

• Returns the full resource representation
• Returns NOT_FOUND (404) if the resource does not exist
• Must be idempotent (same request always returns the same result, barring updates)

List

Retrieves a collection of resources, with pagination support.

# List all topics in a project (paginated)
curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://pubsub.googleapis.com/v1/projects/my-project/topics?pageSize=10"

Pagination parameters:

Parameter	Type	Description
page_size	int32	Max results per page (server may return fewer)
page_token	string	Token from previous response's next_page_token

Pagination response:

{
  "topics": [ ... ],
  "nextPageToken": "abc123"
}

When nextPageToken is empty, there are no more results.

Additional features:

• Filtering: ?filter=labels.env=prod
• Ordering: ?orderBy=createTime desc

Create

Creates a new resource in a collection.

# Create a Pub/Sub topic
curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://pubsub.googleapis.com/v1/projects/my-project/topics/my-new-topic"

Key behaviors:

• The parent resource name is in the URL
• Server assigns a resource ID unless the client provides one
• Returns ALREADY_EXISTS (409) if a resource with that ID already exists
• The response includes the created resource with server-generated fields (name, create_time)

Update

Modifies an existing resource. Uses PATCH for partial updates.

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

Field masks (updateMask):

• Specify which fields to update
• Only listed fields are modified; others remain unchanged
• Omitting the mask updates all fields (full replace)

Mask	Effect
updateMask=labels	Only update labels
updateMask=labels,displayName	Update labels and displayName
(no mask)	Replace entire resource

Delete

Removes a resource.

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

Key behaviors:

• Idempotent: deleting an already-deleted resource may return NOT_FOUND or succeed silently
• May support soft delete: sets delete_time instead of permanent removal
• Soft-deleted resources can be recovered with an Undelete custom method

Standard Methods Flow

Idempotency

Method	Safe	Idempotent
Get	Yes	Yes
List	Yes	Yes
Create	No	No (use request_id for dedup)
Update	No	Yes (same patch = same result)
Delete	No	Yes

TIP

For Create, include a request_id field to make the operation idempotent. If the same request_id is sent twice, the server returns the existing resource instead of creating a duplicate.

See Also

• Custom Methods -- When standard methods are not enough
• Resource Names -- How names appear in method URLs
• Error Handling -- Error responses from standard methods
• HTTP Reference -- HTTP method semantics