Custom Methods (AIP-136)

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

Overview

When the five standard methods (Get, List, Create, Update, Delete) do not fit a use case, Google Cloud APIs use custom methods. Custom methods follow a specific naming and routing pattern.

Naming Pattern

Custom methods use a VerbNoun naming convention:

Pattern	Example
VerbNoun	ArchiveBook, TranslateText, BatchCreateBooks
Verb only (when noun is clear from resource)	Archive, Undelete, Export

URI Pattern

Custom methods use a colon separator (:) in the URI:

POST /v1/{name=publishers/*/books/*}:archive
POST /v1/{parent=publishers/*}/books:batchCreate
POST /v1/text:translate

The colon distinguishes custom methods from sub-resources.

HTTP Method Selection

Use Case	HTTP Method
State-changing operation (mutation)	POST
Read-only operation	GET
Custom method with request body	POST

WARNING

Never use PUT, PATCH, or DELETE for custom methods. Use POST for mutations and GET for reads.

Types of Custom Methods

Resource-Based

Operates on a single resource:

# Archive a specific book
curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://library.googleapis.com/v1/publishers/123/books/456:archive"

Collection-Based

Operates on a collection of resources:

# Batch create books under a publisher
curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{"requests": [{"book": {"title": "Book A"}}, {"book": {"title": "Book B"}}]}' \
  "https://library.googleapis.com/v1/publishers/123/books:batchCreate"

Stateless

Operates without a specific resource context:

# Translate text (no specific resource)
curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{"q": "Hello, world!", "target": "es"}' \
  "https://translation.googleapis.com/v1/text:translate"

Common Custom Method Patterns

Method	Description	HTTP	Example
BatchGet	Get multiple resources at once	GET	/v1/books:batchGet?ids=1&ids=2
BatchCreate	Create multiple resources	POST	/v1/books:batchCreate
BatchUpdate	Update multiple resources	POST	/v1/books:batchUpdate
BatchDelete	Delete multiple resources	POST	/v1/books:batchDelete
Move	Move a resource to a new parent	POST	/v1/books/123:move
Undelete	Restore a soft-deleted resource	POST	/v1/books/123:undelete
Export	Export data	POST	/v1/datasets/123:export
Import	Import data	POST	/v1/datasets/123:import
Cancel	Cancel a long-running operation	POST	/v1/operations/123:cancel

Custom Method Decision Flow

Long-Running Operations (LRO)

When a custom method takes significant time, it should return a long-running operation:

# Start a long export
curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://bigquery.googleapis.com/v1/projects/my-project/datasets/my-dataset:export"

# Response: Operation resource
# { "name": "operations/export-abc123", "done": false }

# Poll for completion
curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://bigquery.googleapis.com/v1/operations/export-abc123"

See Also

• Standard Methods -- The five standard CRUD methods
• Error Handling -- Error responses from custom methods
• API Lifecycle Workflow -- Where custom methods fit