AIP-2716

Standard terms in names

APIs have a lot of identifier names (fields, constants, methods, ...), that often contain terms for things, such as url (getUrl(), doc_url, ...) or id (lookupId(), student_id).

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.

Guidance

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:

• uri for URIs/URLs (as opposed to url, link, href, etc.)
• id for a unique identifier, either globally unique or within a specified context
• index to indicate an ordinal number of an item within a collection, such as message_index on 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 id).

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 id for unique identifiers.

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.