Standard terms in names
APIs have a lot of identifier names (fields, constants, methods, …), that
often contain terms for things, such as
doc_url, …) or
It is useful to have a standard set of terms for common concepts in these
various names. This makes it easier for developers to understand new APIs based
on previous experience. It is not (for example) that
id is a better term than
uid or other options, but it also is not worse, and having different choices
in different APIs is confusing and unnecessary.
This AIP defines terms to use for such common concepts. These terms should be used for the same concept in identifier names.
This is supplemental to the API design guide, which lists standard field names and has other rules about identifiers.
Absent other, more specific guidance, APIs should use the following standard terms (as opposed to alternatives) as parts of identifier names to refer to common concepts, and must not use them to refer to other things:
urifor URIs/URLs (as opposed to
idfor a unique identifier, either globally unique or within a specified context
indexto indicate an ordinal number of an item within a collection, such as
message_indexon a message to say what place it occupies in a stream of message (unless there is a more specific name to use, such as if the number also is used as an ID, use
APIs should avoid use of the term
resource in fields that have resource
names, as this is redundant.
Any more specific guidance overrides these rules. For example, the AIP-122
rule to use
name for the resource name overrides using the term
Fallback to schema.org
If you are looking for standard terms for things, schema.org is a good place to look for terms that have been fairly widely vetted as being normal, customary, and/or clear. You should consult it when choosing identifier names when other strategies fail.