Resource-Oriented Design (AIP-121)

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

Core Concept

Google Cloud APIs are designed around resources -- the fundamental entities that the API manages. Instead of thinking in terms of actions (verbs), you think in terms of things (nouns) and apply standard operations to them.

This approach:

• Maps naturally to HTTP REST and Protocol Buffers / gRPC
• Provides a consistent experience across all Google Cloud APIs
• Makes APIs discoverable and predictable

Resources vs. Actions

Approach	Example	Pattern
Resource-oriented	GET /v1/publishers/123/books/456	Standard method on a resource
Action-oriented	POST /v1/getBook?id=456	Custom verb for each action

Google Cloud APIs use the resource-oriented approach.

API Structure

An API is composed of:

• Service: The top-level entity (e.g., library.googleapis.com)
• Collections: Groups of the same resource type (e.g., publishers, books)
• Resources: Individual entities within a collection (e.g., publishers/123)
• Sub-collections: Nested collections under a resource (e.g., publishers/123/books)

Resource Relationships

Resources can be:

• Top-level: Directly under the API service (/v1/publishers/123)
• Nested: Under a parent resource (/v1/publishers/123/books/456)
• Cross-referenced: One resource references another by name

Standard Fields

All resources should include these common fields (AIP-148):

Field	Type	Description
name	string	Unique resource name
create_time	Timestamp	When the resource was created
update_time	Timestamp	When the resource was last modified
delete_time	Timestamp	When the resource was soft-deleted
display_name	string	Human-readable name
etag	string	For optimistic concurrency control
labels	map	User-defined key-value metadata

Backwards Compatibility (AIP-180)

Safe Changes (backwards-compatible)

• Adding new fields to a response message
• Adding new values to an enum
• Adding new methods or resources
• Adding new optional request fields
• Relaxing constraints (e.g., making a required field optional)

Breaking Changes (NOT backwards-compatible)

• Removing or renaming fields
• Changing field types
• Changing resource name patterns
• Adding required fields to existing requests
• Tightening constraints

TIP

Use major version bumps (v1 to v2) for breaking changes. Always support the previous version for a migration period.

Design Checklist

• [ ] API is modeled around resources (nouns), not actions (verbs)
• [ ] Resources have clear parent-child relationships
• [ ] Standard fields (name, create_time, update_time) are included
• [ ] All changes maintain backwards compatibility (or use a new major version)

See Also

• Resource Names -- How to name resources
• Standard Methods -- CRUD operations on resources
• Custom Methods -- When standard methods are not enough