Resource Names (AIP-122)

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

Overview

Every resource in a Google Cloud API has a unique resource name that identifies it. Resource names are hierarchical, encoding the parent-child relationship between resources.

Resource Name Format

{collection_id}/{resource_id}/{sub_collection_id}/{sub_resource_id}

Examples:

Resource	Resource Name
A publisher	publishers/123
A book by that publisher	publishers/123/books/les-miserables
A shelf in a library	shelves/top-shelf
A book on that shelf	shelves/top-shelf/books/war-and-peace

Full Resource Names

A full resource name includes the API service:

//library.googleapis.com/publishers/123/books/les-miserables

Format: //SERVICE_NAME/RESOURCE_NAME

Full resource names are used for cross-service references and in IAM policies.

Collection Identifiers

Rules for collection names:

Rule	Correct	Incorrect
Must be plural	publishers	publisher
Use camelCase	shelfBooks	shelf_books
Use lowercase first letter	publishers	Publishers
Must be concrete nouns	books	items

Resource IDs

Rules for resource IDs:

Rule	Details
Character set	a-z, 0-9, hyphens (DNS-compatible)
Case	Lowercase preferred
Length	1-63 characters recommended
Uniqueness	Must be unique within the parent collection
Immutability	Cannot change after creation

Server-assigned IDs are generated by the API (e.g., numeric IDs). Client-assigned IDs are provided by the caller (e.g., my-custom-bucket).

Resource Name Hierarchy

Resource Names Are NOT URLs

Resource names can be mapped to URLs but are not URLs themselves:

Resource Name	REST URL
publishers/123/books/456	https://library.googleapis.com/v1/publishers/123/books/456
projects/my-proj/topics/my-topic	https://pubsub.googleapis.com/v1/projects/my-proj/topics/my-topic

The URL includes:

• The service hostname
• The API version (v1, v2)
• The resource name

Singleton Resources

Some resources exist without a collection (exactly one instance):

publishers/123/settings

Singletons do not have a resource ID -- the collection name itself identifies the resource.

Wildcard in Resource Names

Use - as a wildcard to match all resources in a collection:

publishers/-/books/-    # All books across all publishers
projects/-/topics/-     # All topics across all projects

Best Practices

1. Keep names stable -- Resource names should not change after creation
2. Use meaningful IDs -- Prefer buckets/analytics-data over buckets/b123456
3. Avoid encoding data -- Do not embed metadata in resource names
4. Use consistent depth -- Similar resources should have similar nesting depth

See Also

• Resource-Oriented Design -- The design philosophy behind resource names
• Standard Methods -- How resource names are used in CRUD operations
• Naming Conventions -- Broader naming rules