● Home  


Docs  


Cloud APIs  


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 should be:

●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 should be in correct American English. For example, license (instead of licence), color (instead of colour).
●Commonly accepted short forms or abbreviations of long words may be 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 may be 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 must be consistently used by APIs, UIs, documentation, Terms of Service, billing statements, commercial contracts, etc. Google APIs must use 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.
API Name Example
Product Name Google Calendar API
Service Name calendar.googleapis.com
Package Name google.calendar.v3
Interface Name google.calendar.v3.CalendarService
Source Directory //google/calendar/v3
API Name calendar

Service names


Service names should be 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 should be 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.comand buildresults.googleapis.com are both services that are part of the Google Build API.

Package names


Package names declared in the API .proto files should be consistent with Product Names and Service Names. Package names should use singular component names to avoid mixed singular and plural component names. Package names must not use underscores. Package names for versioned APIs must end 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, should use proto package names consistent with the Product name:
 
// Google Watcher API
package google.watcher.v1;

Java package names specified in the API .proto files must match 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 should use 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 servicein 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 should use an intuitive noun such as Calendar or Blob. The name should not conflict 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 ApiorService) should be 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 should follow the naming convention of VerbNounin upper camel case, where the noun is typically the resource type.
Verb Noun Method name Request message Response message
List Book ListBooks ListBooksRequest ListBooksResponse
Get Book GetBook GetBookRequest Book
Create Book CreateBook CreateBookRequest Book
Update Book UpdateBook UpdateBookRequest Book
Rename Book RenameBook RenameBookRequest RenameBookResponse
Delete Book DeleteBook DeleteBookRequest google.protobuf.Empty

The verb portion of the method name should use 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 must be singular for all methods except List, and must be plural for List. For custom methods, the noun may be singular or plural as appropriate. Batch methods must use 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 IsBookPublisherApprovedorNeedsPublisherApproval. To remain in the imperative mood in situations like this, rely on commands such as "check" (CheckBookPublisherApproved) and "validate" (ValidateBookPublisher).
Method names should not include 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 CreateBookmessage already exists and you are considering adding CreateBookFromDictation, consider a TranscribeBookmethod instead.

Message names


Message names should be 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 SharedinSharedProxySettingsis unnecessary if there are no unshared proxy settings.
Message names should not include 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 should be named after the method names with the suffix Requestand 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 must use UpperCamelCase names.
Enum values must use CAPITALIZED_NAMES_WITH_UNDERSCORES. Each enum value must end with a semicolon, not a comma. The first value should be 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 0value has meaning other than UNSPECIFIEDshould be named with the suffix Valueand 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 must use 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 not include prepositions (e.g. "for", "during", "at"), for example:

●reason_for_error should instead be error_reason
●cpu_usage_at_time_of_failureshould instead be failure_time_cpu_usage

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

●items_collected should instead be collected_items
●objects_importedshould instead be imported_objects

Repeated field names


Repeated fields in APIs must use 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 should be used, and the field name should end with time, such as start_timeand end_time.
If the time refers to an activity, the field name should have the form of verb_time, such as create_time, update_time. Avoid using past tense for the verb, such as created_timeorlast_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 should be 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 must have 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 not include any unit suffix. The string representation should use 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 should be 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 should be 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 must include the unit of measurement.
 
xxx_{bytes|width_pixels|meters}

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

List filter field


If an API supports filtering of resources returned by the Listmethod, the field containing the filter expression should be 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 Listmethod's response message, which contains the list of resources must be a plural form of the resource name itself. For example, a method CalendarApi.ListEvents()must define a response message ListEventsResponsewith a repeated field called eventsfor 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 must use 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 should be 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 should be used. Examples:

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


 



Previous
   Errors  


Next
   Design Patterns