From 93ec8c7a4a94c31945026a05ed883c6c5f893526 Mon Sep 17 00:00:00 2001 From: noahdietz Date: Tue, 10 Jun 2025 15:22:51 -0700 Subject: [PATCH 1/2] feat(AIP-190): add general naming AIP --- aip/general/0190.md | 156 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 156 insertions(+) create mode 100644 aip/general/0190.md diff --git a/aip/general/0190.md b/aip/general/0190.md new file mode 100644 index 0000000000..ae60ccea55 --- /dev/null +++ b/aip/general/0190.md @@ -0,0 +1,156 @@ +--- +id: 190 +state: approved +created: 2025-06-10 +placement: + category: polish + order: 0 +--- + +# 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: + +- stamp +- 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](https://google.github.io/styleguide/javaguide.html#s5.3-camel-case). +- 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](./0009.md#api-service-name) such as +`pubsub.googleapis.com`, the term *interface name* refers to the name +used when defining a `service` in a .proto file: + +```proto +// 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: + +Method | Standard | Batch +------ | -------- | ----- +`Get` | [AIP-131][] | [AIP-231][] +`List` | [AIP-132][] | N/A +`Create` | [AIP-133][] | [AIP-233][] +`Update` | [AIP-134][] | [AIP-234][] +`Delete` | [AIP-135][] | [AIP-235][] + +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](https://google.aip.dev/general#operations). + +## Further reading + +- For proto and language package naming, see AIP-191. +- For collection ID naming conventions, see + [AIP-122](./0122.md#collection-identifiers). +- For Enum names, see AIP-126. +- For field names, see AIP-140. +- For repeated field names, see [AIP-140](./0140#repeated-fields). +- For fields representing times and durations, see AIP-142. +- For fields representing dates and times of day, see + [AIP-142](./0142#civil-dates-and-times). +- For fields representing a quantity, see AIP-141. +- For the canonical `List` method `filter` field, see + [AIP-132](./0132#filtering). +- For the canonical `List` response message, see + [AIP-132](./0132#response-message). +- For well known abbreviations, see [AIP-140](./0140#abbreviations). + + +[AIP-131]: ./0131.md +[AIP-132]: ./0132.md +[AIP-133]: ./0133.md +[AIP-134]: ./0134.md +[AIP-135]: ./0135.md +[AIP-231]: ./0231.md +[AIP-233]: ./0233.md +[AIP-234]: ./0234.md +[AIP-235]: ./0235.md From be3e8d7fd7c13406b9e32a34c88d95489245cea3 Mon Sep 17 00:00:00 2001 From: noahdietz Date: Tue, 10 Jun 2025 15:27:45 -0700 Subject: [PATCH 2/2] chore: fix typo --- aip/general/0190.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aip/general/0190.md b/aip/general/0190.md index ae60ccea55..96883a9665 100644 --- a/aip/general/0190.md +++ b/aip/general/0190.md @@ -17,7 +17,7 @@ general, these conventions apply to all Google-managed services. 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: -- stamp +- straightforward - intuitive - consistent