@@ -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
357385Using 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