AIP-190

Naming conventions

This topic describes the naming conventions used in Google APIs. In general, these conventions apply to all Google-managed services.

Guidance

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:

• straightforward
• intuitive
• consistent

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

Since English is a second language for many developers, one goal of these naming conventions is to make every API name understandable to the majority of developers. 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.
• Unless otherwise specified, definitions must use UpperCamelCase names, as defined by Google Java Style.
• 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.

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 should use an intuitive noun such as Calendar or BlobStore. 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 Api or Service) should be used to disambiguate.

Method names

A service may, in its IDL specification, define one or more API methods that correspond to methods on collections and resources. The method names should follow the naming convention of VerbNoun in UpperCamelCase, where the noun is typically the resource type.

Standard methods, and their Batch variants, define their naming guidance in the following documents:

All other methods are considered Custom Methods and adhere to AIP-136 naming guidance.

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 Shared in SharedProxySettings is 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

For request and response message names, see AIP-136 for custom methods and the appropriate AIP for standard methods.

Further reading

• For proto and language package naming, see AIP-191.
• For collection ID naming conventions, see AIP-122.
• For Enum names, see AIP-126.
• For field names, see AIP-140.
• For repeated field names, see AIP-140.
• For fields representing times and durations, see AIP-142.
• For fields representing dates and times of day, see AIP-142.
• For fields representing a quantity, see AIP-141.
• For the canonical List method filter field, see AIP-132.
• For the canonical List response message, see AIP-132.
• For well known abbreviations, see AIP-140.