Skip to content

Commit 90ab3ab

Browse files
noahdietznoahdietz
authored
feat(AIP-190): add general naming AIP (#1525)
1 parent e96e08c commit 90ab3ab

1 file changed

Lines changed: 156 additions & 0 deletions

File tree

‎aip/general/0190.md‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
---
2+
id: 190
3+
state: approved
4+
created: 2025-06-10
5+
placement:
6+
category: polish
7+
order: 0
8+
---
9+
10+
# Naming conventions
11+
12+
This topic describes the naming conventions used in Google APIs. In
13+
general, these conventions apply to all Google-managed services.
14+
15+
## Guidance
16+
17+
In order to provide consistent developer experience across many APIs and
18+
over a long period of time, all names used by an API **should** be:
19+
20+
- straightforward
21+
- intuitive
22+
- consistent
23+
24+
This includes names of interfaces, resources, collections, methods, and
25+
messages.
26+
27+
Since English is a second language for many developers, one goal of these
28+
naming conventions is to make every API name understandable to the majority of
29+
developers. It does this by encouraging the use of a simple, consistent, and
30+
small vocabulary when naming methods and resources.
31+
32+
- Names used in APIs **should** be in correct American English. For
33+
example, license (instead of licence), color (instead of colour).
34+
- Commonly accepted short forms or abbreviations of long words **may**
35+
be used for brevity. For example, API is preferred over Application
36+
Programming Interface.
37+
- Unless otherwise specified, definitions **must** use UpperCamelCase names,
38+
as defined by
39+
[Google Java Style](https://google.github.io/styleguide/javaguide.html#s5.3-camel-case).
40+
- Use intuitive, familiar terminology where possible. For example,
41+
when describing removing (and destroying) a resource, delete is
42+
preferred over erase.
43+
- Use the same name or term for the same concept, including for
44+
concepts shared across APIs.
45+
- Avoid name overloading. Use different names for different concepts.
46+
- Avoid overly general names that are ambiguous within the context of
47+
the API and the larger ecosystem of Google APIs. They can lead to
48+
misunderstanding of API concepts. Rather, choose specific names that
49+
accurately describe the API concept. This is particularly important
50+
for names that define first-order API elements, such as resources.
51+
There is no definitive list of names to avoid, as every name must be
52+
evaluated in the context of other names. Instance, info, and service
53+
are examples of names that have been problematic in the past. Names
54+
chosen should describe the API concept clearly (for example:
55+
instance of what?) and distinguish it from other relevant concepts
56+
(for example: does "alert" mean the rule, the signal, or the
57+
notification?).
58+
- Carefully consider use of names that may conflict with keywords in
59+
common programming languages. Such names **may** be used but will
60+
likely trigger additional scrutiny during API review. Use them
61+
judiciously and sparingly.
62+
63+
### Interface names
64+
65+
To avoid confusion with [Service Names](./0009.md#api-service-name) such as
66+
`pubsub.googleapis.com`, the term *interface name* refers to the name
67+
used when defining a `service` in a .proto file:
68+
69+
```proto
70+
// Library is the interface name.
71+
service Library {
72+
rpc ListBooks(...) returns (...);
73+
rpc ...
74+
}
75+
```
76+
77+
You can think of the *service name* as a reference to the actual
78+
implementation of a set of APIs, while the *interface name* refers to
79+
the abstract definition of an API.
80+
81+
An interface name **should** use an intuitive noun such as Calendar or
82+
BlobStore. The name **should not** conflict with any well-established
83+
concepts in programming languages and their runtime libraries (for
84+
example, File).
85+
86+
In the rare case where an *interface name* would conflict with another
87+
name within the API, a suffix (for example `Api` or `Service`)
88+
**should** be used to disambiguate.
89+
90+
### Method names
91+
92+
A service **may**, in its IDL specification, define one or more API
93+
methods that correspond to methods on collections and resources. The
94+
method names **should** follow the naming convention of `VerbNoun` in
95+
UpperCamelCase, where the noun is typically the resource type.
96+
97+
Standard methods, and their Batch variants, define their naming guidance in
98+
the following documents:
99+
100+
Method | Standard | Batch
101+
------ | -------- | -----
102+
`Get` | [AIP-131][] | [AIP-231][]
103+
`List` | [AIP-132][] | N/A
104+
`Create` | [AIP-133][] | [AIP-233][]
105+
`Update` | [AIP-134][] | [AIP-234][]
106+
`Delete` | [AIP-135][] | [AIP-235][]
107+
108+
All other methods are considered Custom Methods and adhere to AIP-136 naming
109+
guidance.
110+
111+
### Message names
112+
113+
Message names **should** be short and concise. Avoid unnecessary or redundant
114+
words. Adjectives can often be omitted if there is no corresponding message
115+
without the adjective. For example, the `Shared` in `SharedProxySettings` is
116+
unnecessary if there are no _unshared_ proxy settings.
117+
118+
Message names **should not** include prepositions (e.g. "With", "For").
119+
Generally, message names with prepositions are better represented with
120+
optional fields on the message.
121+
122+
#### Request and response messages
123+
124+
For request and response message names, see AIP-136 for custom methods and the
125+
appropriate AIP for
126+
[standard methods](https://google.aip.dev/general#operations).
127+
128+
## Further reading
129+
130+
- For proto and language package naming, see AIP-191.
131+
- For collection ID naming conventions, see
132+
[AIP-122](./0122.md#collection-identifiers).
133+
- For Enum names, see AIP-126.
134+
- For field names, see AIP-140.
135+
- For repeated field names, see [AIP-140](./0140#repeated-fields).
136+
- For fields representing times and durations, see AIP-142.
137+
- For fields representing dates and times of day, see
138+
[AIP-142](./0142#civil-dates-and-times).
139+
- For fields representing a quantity, see AIP-141.
140+
- For the canonical `List` method `filter` field, see
141+
[AIP-132](./0132#filtering).
142+
- For the canonical `List` response message, see
143+
[AIP-132](./0132#response-message).
144+
- For well known abbreviations, see [AIP-140](./0140#abbreviations).
145+
146+
<!-- Need these link values for the table entries which won't be hot-linked by
147+
the site-generator like plain text would be -->
148+
[AIP-131]: ./0131.md
149+
[AIP-132]: ./0132.md
150+
[AIP-133]: ./0133.md
151+
[AIP-134]: ./0134.md
152+
[AIP-135]: ./0135.md
153+
[AIP-231]: ./0231.md
154+
[AIP-233]: ./0233.md
155+
[AIP-234]: ./0234.md
156+
[AIP-235]: ./0235.md

0 commit comments

Comments
 (0)