Skip to content

Commit 700ad05

Browse files
authored
chore(AIP-122): add some rationale for resource names (#1430)
1 parent 082e4d1 commit 700ad05

1 file changed

Lines changed: 30 additions & 0 deletions

File tree

aip/general/0122.md

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -352,6 +352,34 @@ message Book {
352352

353353
## Rationale
354354

355+
### Using names instead of IDs
356+
357+
For any large system, there are many kinds of resources. To use simple resource
358+
IDs to identify a resource, we'd actually need use a resource-specific tuple to
359+
reliably identify it, such as `(bucket, object)` or `(user, album, photo)`. This
360+
creates several issues:
361+
362+
* Developers have to understand and remember such anonymous tuples.
363+
* Passing tuples is generally harder than passing strings.
364+
* Centralized infrastructures, such as logging and access control systems,
365+
don't understand specialized tuples.
366+
* Specialized tuples limit API design flexibility, such as providing
367+
reusable API interfaces. For example,
368+
[Long Running Operations][aip-151] can work with many other API interfaces
369+
because they use flexible resource names.
370+
371+
[aip-151]: ./0151.md
372+
373+
### Standardizing on `name`
374+
375+
The concept of resource names is not a new one, and is formalized in Uniform
376+
Resource Names (URN) in conjunction with Uniform Resource Identifiers (URI) and
377+
Uniform Resource Locators (URL). Considering that the term "name" is so heavily
378+
overloaded in general, usage outside of a very well-defined meaning would be
379+
confusing for developers. So, the field name `name` is reserved in the context
380+
of AIP-compliant APIs so as to eliminate any confusion with resource names, and
381+
force other would be "name" fields to use a more specific field name.
382+
355383
### Disallow embedding of resources
356384

357385
Using a resource message directly as the type of a field within another resource
@@ -374,6 +402,8 @@ isolation of logical concerns per-resource.
374402

375403
## Changelog
376404

405+
- **2024-10-15**: Add some rationale we found for use of `name` as a field and
406+
instead of IDs as an identifier.
377407
- **2024-06-14**: Clarify resource annotation shortening rules for nested
378408
collections.
379409
- **2023-09-19**: Prohibit duplicate collection identifiers.

0 commit comments

Comments
 (0)