Naming conventions

In order to provide consistent developer experience across many APIs and over a long period of time, all names used by an API shouldbe:

• simple
• intuitive
• consistent

This includes names of interfaces, resources, collections, methods, and messages.

Since many developers are not native English speakers, one goal of these naming conventions is to ensure that the majority of developers can easily understand an API. It does this by encouraging the use of a simple, consistent, and small vocabulary when naming methods and resources.

• Names used in APIs shouldbe in correct American English. For example, license (instead of licence), color (instead of colour).
• Commonly accepted short forms or abbreviations of long words maybe used for brevity. For example, API is preferred over Application Programming Interface.
• Use intuitive, familiar terminology where possible. For example, when describing removing (and destroying) a resource, delete is preferred over erase.
• Use the same name or term for the same concept, including for concepts shared across APIs.
• Avoid name overloading. Use different names for different concepts.
• Avoid overly general names that are ambiguous within the context of the API and the larger ecosystem of Google APIs. They can lead to misunderstanding of API concepts. Rather, choose specific names that accurately describe the API concept. This is particularly important for names that define first-order API elements, such as resources. There is no definitive list of names to avoid, as every name must be evaluated in the context of other names. Instance, info, and service are examples of names that have been problematic in the past. Names chosen should describe the API concept clearly (for example: instance of what?) and distinguish it from other relevant concepts (for example: does "alert" mean the rule, the signal, or the notification?).
• Carefully consider use of names that may conflict with keywords in common programming languages. Such names maybe used but will likely trigger additional scrutiny during API review. Use them judiciously and sparingly.

Product names

Product names refer to the product marketing names of APIs, such as Google Calendar API . Product names mustbe consistently used by APIs, UIs, documentation, Terms of Service, billing statements, commercial contracts, etc. Google APIs mustuse product names approved by the product and marketing teams.

The table below shows examples of all related API names and their consistency. See further below on this page for more details on the respective names and their conventions.

Service names

Service names shouldbe syntactically valid DNS names (as per RFC 1035 ) which can be resolved to one or more network addresses. The service names of public Google APIs follow the pattern: xxx.googleapis.com . For example, the service name of the Google Calendar is calendar.googleapis.com .

If an API is composed of several services they shouldbe named in a way to help discoverability. One way to do this is for the Service Names to share a common prefix. For example the services build.googleapis.com and buildresults.googleapis.com are both services that are part of the Google Build API.

Package names

Package names declared in the API .proto files shouldbe consistent with Product Names and Service Names. Package names shoulduse singular component names to avoid mixed singular and plural component names. Package names must notuse underscores. Package names for versioned APIs mustend with the version. For example:

  // Google Calendar API 
 package 
  
 google 
 . 
 calendar.v3 
 ; 
 

An abstract API that isn't directly associated with a service, such as Google Watcher API, shoulduse proto package names consistent with the Product name:

  // Google Watcher API 
 package 
  
 google 
 . 
 watcher.v1 
 ; 
 

Java package names specified in the API .proto files mustmatch the proto package names with standard Java package name prefix ( com. , edu. , net. , etc). For example:

  package 
  
 google 
 . 
 calendar.v3 
 ; 
 // Specifies Java package name, using the standard prefix "com. 
" option 
  
 java_package 
  
 = 
  
" com.google.calendar.v3 
" ; 
 

Collection IDs

Collection IDs shoulduse plural form and lowerCamelCase , and American English spelling and semantics. For example: events , children , or deletedEvents .

Interface names

To avoid confusion with Service Names such as pubsub.googleapis.com , the term interface name refers to the name used when defining a service in a .proto file:

  // Library is the interface name. 
 service 
  
 Library 
  
 { 
  
 rpc 
  
 ListBooks 
 ( 
 ... 
 ) 
  
 returns 
  
 ( 
 ... 
 ); 
  
 rpc 
  
 ... 
 } 
 

You can think of the service name as a reference to the actual implementation of a set of APIs, while the interface name refers to the abstract definition of an API.

An interface name shoulduse an intuitive noun such as Calendar or Blob. The name should notconflict with any well-established concepts in programming languages and their runtime libraries (for example, File).

In the rare case where an interface name would conflict with another name within the API, a suffix (for example Api or Service ) shouldbe used to disambiguate.

Method names

A service may, in its IDL specification, define one or more RPC methods that correspond to methods on collections and resources. The method names shouldfollow the naming convention of VerbNoun in upper camel case, where the noun is typically the resource type.

The verb portion of the method name shoulduse the imperative mood , which is for orders or commands rather than the indicative mood which is for questions.

For standard methods, the noun portion of the method name mustbe singular for all methods except List , and mustbe plural for List . For custom methods, the noun maybe singular or plural as appropriate. Batch methods mustuse the plural noun.

This is easily confused when the verb is asking a question about a sub-resource in the API, which is often expressed in the indicative mood. For example, ordering the API to create a book is clearly CreateBook (in the imperative mood), but asking the API about the state of the book's publisher might use the indicative mood, such as IsBookPublisherApproved or NeedsPublisherApproval . To remain in the imperative mood in situations like this, rely on commands such as "check" ( CheckBookPublisherApproved ) and "validate" ( ValidateBookPublisher ).

Method names should notinclude prepositions (e.g. "For", "With", "At", "To"). Generally, method names with prepositions indicate that a new method is being used where a field should instead be added to an existing method, or the method should use a distinct verb.

For example, if a CreateBook message already exists and you are considering adding CreateBookFromDictation , consider a TranscribeBook method instead.

Message names

Message names shouldbe short and concise. Avoid unnecessary or redundant words. Adjectives can often be omitted if there is no corresponding message without the adjective. For example, the Shared in SharedProxySettings is unnecessary if there are no unshared proxy settings.

Message names should notinclude prepositions (e.g. "With", "For"). Generally, message names with prepositions are better represented with optional fields on the message.

Request and response messages

The request and response messages for RPC methods shouldbe named after the method names with the suffix Request and Response , respectively, unless the method request or response type is:

• an empty message (use google.protobuf.Empty ),
• a resource type, or
• a resource representing an operation

This typically applies to requests or responses used in standard methods Get , Create , Update , or Delete .

Enum names

Enum types mustuse UpperCamelCase names.

Enum values mustuse CAPITALIZED_NAMES_WITH_UNDERSCORES. Each enum value mustend with a semicolon, not a comma. The first value shouldbe named ENUM_TYPE_UNSPECIFIED as it is returned when an enum value is not explicitly specified.

  enum 
  
 FooBar 
  
 { 
  
 // The first value represents the default and must be == 0. 
  
 FOO_BAR_UNSPECIFIED 
  
 = 
  
 0 
 ; 
  
 FIRST_VALUE 
  
 = 
  
 1 
 ; 
  
 SECOND_VALUE 
  
 = 
  
 2 
 ; 
 } 
 

Wrappers

Messages encapsulating proto2 enum types where the 0 value has meaning other than UNSPECIFIED shouldbe named with the suffix Value and have a single field named value .

  enum 
  
 OldEnum 
  
 { 
  
 VALID 
  
 = 
  
 0 
 ; 
  
 OTHER_VALID 
  
 = 
  
 1 
 ; 
 } 
 message 
  
 OldEnumValue 
  
 { 
  
 OldEnum 
  
 value 
  
 = 
  
 1 
 ; 
 } 
 

Field names

Field definitions in the .proto files mustuse lower_case_underscore_separated_names. These names will be mapped to the native naming convention in generated code for each programming language.

Field names should notinclude prepositions (e.g. "for", "during", "at"), for example:

• reason_for_error should instead be error_reason
• cpu_usage_at_time_of_failure should instead be failure_time_cpu_usage

Field names should notuse postpositive adjectives (modifiers placed after the noun), for example:

• items_collected should instead be collected_items
• objects_imported should instead be imported_objects

Repeated field names

Repeated fields in APIs mustuse proper plural forms. This matches the convention of existing Google APIs, and the common expectation of external developers.

Time and Duration

To represent a point in time independent of any time zone or calendar, google.protobuf.Timestamp shouldbe used, and the field name shouldend with time , such as start_time and end_time .

If the time refers to an activity, the field name shouldhave the form of verb_time , such as create_time , update_time . Avoid using past tense for the verb, such as created_time or last_updated_time .

To represent a span of time between two points in time independent of any calendar and concepts like "day" or "month", google.protobuf.Duration shouldbe used.

  message 
  
 FlightRecord 
  
 { 
  
 google.protobuf.Timestamp 
  
 takeoff_time 
  
 = 
  
 1 
 ; 
  
 google.protobuf.Duration 
  
 flight_duration 
  
 = 
  
 2 
 ; 
 } 
 

If you have to represent time-related fields using an integer type for legacy or compatibility reasons, including wall-clock time, duration, delay and latency, the field names musthave the following form:

 xxx_{time|duration|delay|latency}_{seconds|millis|micros|nanos} 

  message 
  
 Email 
  
 { 
  
 int64 
  
 send_time_millis 
  
 = 
  
 1 
 ; 
  
 int64 
  
 receive_time_millis 
  
 = 
  
 2 
 ; 
 } 
 

If you have to represent timestamp using string type for legacy or compatibility reasons, the field names should notinclude any unit suffix. The string representation shoulduse RFC 3339 format, e.g. "2014-07-30T10:43:17Z".

Date and Time of Day

For dates that are independent of time zone and time of day, google.type.Date shouldbe used and it should have the suffix _date . If a date must be represented as a string, it should be in the ISO 8601 date format YYYY-MM-DD, e.g. 2014-07-30.

For times of day that are independent of time zone and date, google.type.TimeOfDay shouldbe used and should have the suffix _time . If a time of day must be represented as a string, it should be in the ISO 8601 24-hour time format HH:MM:SS[.FFF], e.g. 14:55:01.672.

  message 
  
 StoreOpening 
  
 { 
  
 google.type.Date 
  
 opening_date 
  
 = 
  
 1 
 ; 
  
 google.type.TimeOfDay 
  
 opening_time 
  
 = 
  
 2 
 ; 
 } 
 

Quantities

Quantities represented by an integer type mustinclude the unit of measurement.

 xxx_{bytes|width_pixels|meters} 

If the quantity is a number of items, then the field shouldhave the suffix _count , for example node_count .

List filter field

If an API supports filtering of resources returned by the List method, the field containing the filter expression shouldbe named filter . For example:

  message 
  
 ListBooksRequest 
  
 { 
  
 // The parent resource name. 
  
 string 
  
 parent 
  
 = 
  
 1 
 ; 
  
 // The filter expression. 
  
 string 
  
 filter 
  
 = 
  
 2 
 ; 
 } 
 

List response

The name of the field in the List method's response message, which contains the list of resources mustbe a plural form of the resource name itself. For example, a method CalendarApi.ListEvents() mustdefine a response message ListEventsResponse with a repeated field called events for the list of returned resources.

  service 
  
 CalendarApi 
  
 { 
  
 rpc 
  
 ListEvents 
 ( 
 ListEventsRequest 
 ) 
  
 returns 
  
 ( 
 ListEventsResponse 
 ) 
  
 { 
  
 option 
  
 ( 
 google.api.http 
 ) 
  
 = 
  
 { 
  
 get 
 : 
  
" / 
 v3 
 / 
 { 
 parent 
 = 
 calendars 
 / 
 * 
 } 
 / 
 events 
" ; 
  
 }; 
  
 } 
 } 
 message 
  
 ListEventsRequest 
  
 { 
  
 string 
  
 parent 
  
 = 
  
 1 
 ; 
  
 int32 
  
 page_size 
  
 = 
  
 2 
 ; 
  
 string 
  
 page_token 
  
 = 
  
 3 
 ; 
 } 
 message 
  
 ListEventsResponse 
  
 { 
  
 repeated 
  
 Event 
  
 events 
  
 = 
  
 1 
 ; 
  
 string 
  
 next_page_token 
  
 = 
  
 2 
 ; 
 } 
 

Camel case

Except for field names and enum values, all definitions inside .proto files mustuse UpperCamelCase names, as defined by Google Java Style .

Name abbreviation

For well known name abbreviations among software developers, such as config and spec , the abbreviations shouldbe used in API definitions instead of the full spelling. This will make the source code easy to read and write. In formal documentations, the full spelling shouldbe used. Examples:

• config (configuration)
• id (identifier)
• spec (specification)
• stats (statistics)