Naming Conventions (AIP-190)

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

Overview

Consistent naming is critical for API usability and developer experience. Google Cloud APIs follow strict naming conventions defined in AIP-190.

General Rules

1. Use American English spelling (e.g., "color" not "colour")
2. Use simple, intuitive nouns for resource types
3. Avoid abbreviations except well-known ones (API, URL, HTTP, ID, DNS, CPU, GPU)
4. Do not use brand names or project-internal jargon

Naming by Entity Type

Entity	Case	Example
Service name	lower.dot.case	library.googleapis.com
Package name	lower.dot.case	google.library.v1
Interface/Service	UpperCamelCase	LibraryService
Method	UpperCamelCase	ListBooks, GetBook
Message type	UpperCamelCase	ListBooksRequest, ListBooksResponse
Field name	lower_snake_case	display_name, page_size
Enum type	UpperCamelCase	BookFormat
Enum value	UPPER_SNAKE_CASE	BOOK_FORMAT_PDF, BOOK_FORMAT_EPUB
Oneof name	lower_snake_case	delivery_method

Method Naming

Standard Methods

Standard methods always use these exact names:

Method	Name	Request Message	Response Message
Get	GetBook	GetBookRequest	Book
List	ListBooks	ListBooksRequest	ListBooksResponse
Create	CreateBook	CreateBookRequest	Book
Update	UpdateBook	UpdateBookRequest	Book
Delete	DeleteBook	DeleteBookRequest	google.protobuf.Empty

Custom Methods

Custom methods use VerbNoun pattern:

Correct	Incorrect	Why
ArchiveBook	BookArchive	Verb comes first
BatchCreateBooks	CreateBooksBatch	"Batch" prefix for batch operations
TranslateText	DoTranslation	Use specific verbs, not "Do"
ExportData	DataExport	Verb first

Field Naming

Common Field Names

Field	Type	Description
name	string	Resource name
display_name	string	Human-readable name
title	string	Official title
description	string	Longer explanation
create_time	Timestamp	Creation time
update_time	Timestamp	Last modification time
delete_time	Timestamp	Soft-deletion time
expire_time	Timestamp	Expiration time
start_time	Timestamp	Start of a time range
end_time	Timestamp	End of a time range
etag	string	Concurrency control
labels	map	User metadata
filter	string	List filter expression
page_size	int32	List page size
page_token	string	List pagination token
order_by	string	List sort order
request_id	string	Idempotency key

Field Name Rules

Rule	Correct	Incorrect
Use snake_case	display_name	displayName
Use singular for scalars	book_count	books_count
Use plural for repeated	books	book (for a list)
Suffix booleans	is_active, has_children	active, children_exist
Suffix time fields with _time	create_time	created, created_at
Suffix duration fields with _duration	timeout_duration	timeout

Enum Naming

enum BookFormat {
  BOOK_FORMAT_UNSPECIFIED = 0;  // Always include UNSPECIFIED as 0
  BOOK_FORMAT_PDF = 1;
  BOOK_FORMAT_EPUB = 2;
  BOOK_FORMAT_HARDCOVER = 3;
}

Rules:

• Prefix each value with the enum type name in UPPER_SNAKE_CASE
• Always include an UNSPECIFIED value as 0
• UNSPECIFIED must be the first value

Naming Hierarchy

Words to Avoid

Avoid	Use Instead	Reason
info, data	Specific noun	Too vague
object, item	Specific resource type	Too generic
get_data	list_metrics	Be specific
type (as field name)	format, kind	Reserved word in many languages
config	configuration	Avoid abbreviation

See Also

• Resource Names -- Naming rules for resources specifically
• Standard Methods -- Method naming patterns
• Error Handling -- Error naming conventions