feat(AIP-217): reformat guidance and explicitly state name format (#1393)

Author: noahdietz

aip/general/0217.md

@@ -38,20 +38,44 @@ message ListBooksResponse {
 
 - The field **must** be a repeated string, and **should** be named
   `unreachable`.
-- The field **must** be set to the names of the resources which are the cause
-  of the issue, such as the parent or individual resources that could not be
-  reached. The objects listed as unreachable **may** be _parents_ (or higher
-  ancestors) rather than the individual resources being requested. For example,
-  if a location is unreachable, the location is listed.
-  - The response **must not** provide any other information about the issue,
-    such as error details or codes. To discover what the underlying issue is,
-    users **should** send a more specific request.
-  - The service **must** provide a way for the user to get an error with
-    additional information, and **should** allow the user to repeat the
-    original call with more restrictive parameters in order to do so.
-  - The resource names provided in this field **may** be heterogeneous. The
-    field **should** document what potential resources may be provided in this
-    field, and note that it might expand later.
+- The field **must** contain the resource names of the resources that are
+  unreachable or those that impede reaching the requested collection, such as
+  the parent resource of the collection that could not be reached.
+  - For example, if an entire location is unreachable, preventing access to the
+    localized collection of resources requested, the location resource is
+    included.
+- The field **must** contain _service-relative_ resource names, and **must not**
+  contain full resource names, resource URIs, or simple resource IDs. See
+  [AIP-122][aip-122] for definitions.
+  - For example, if a `Book` resource is unreachable, the _service-relative_
+    resource name `"shelves/scifi1/books/starwars4"` is included in
+    `unreachable`, as opposed to the _full_ resource name
+    `"//library.googleapis.com/shelves/scifi1/books/starwars4"`, the
+    _parent-relative_ resource `"books/starwars4"`, the resource ID
+    `"starwars4"`, or the resource URI.
+- The response **must not** provide any other information about the issue(s)
+  that made the listed resources unreachable.
+  - For example, the response cannot contain an extra field with error reasons
+    for each `unreachable` entry.
+- The service **must** provide a way for the user to make a more specific
+  request and receive an error with additional information e.g. via a Standard
+  Get or a Standard List targeted at the unreachable collection parent.
+  - The service **must** also allow the user to repeat the original call with
+    more restrictive parameters.
+- The resource names that appear in `unreachable` **may** be heterogeneous.
+  - The `unreachable` field definition **should** document what potential
+    resources could be provided in this field, and note that it might expand
+    later.
+  - For example, if both an entire location and a specific resource in a
+    different location are unreachable, the unreachable location's name 
+    e.g. `"projects/example123/locations/us-east1"` and the unreachable
+    resource's name e.g.
+    `"projects/example123/locations/europe-west2/instances/example456"` will
+    both appear in `unreachable`.
+
+[aip-122]: ./0122.md
+[aip-160]: ./0160.md
+
 
 **Important:** If a single unreachable location or resource prevents returning
 any data by definition (for example, a list request for a single publisher
@@ -146,6 +170,27 @@ resource collection. The supported granularity **must** be documented on the
 
 ## Rationale
 
+### Using service-relative resource names
+
+In general, relative resource names, as defined in AIP-122, are the best
+practice for referring to resources by name _within_ a service and in other
+services when that other service is obvious. The full resource name format is
+strictly less consumable (e.g., requires extra parsing client side), and
+over-specified for the uses of `unreachable`. Resource URIs are not transport
+agnostic, as they are unusable in standard methods for gRPC users, and simple
+resource IDs do not provide enough information about exactly which resource
+was unreachable in a heterogenous list of resources.
+
+### Minimizing extra error details in response
+
+The context in which an unreachable resource is discovered may be sensitive and
+the state of the system fluid between calls. As such, it is preferred to defer
+to the service by making a more specific RPC to get more details about a
+specific resource or parent. This allows the parent to handle all necessary RPC
+checks and system state resolution on at time of request, rather than by
+shoehorning potentially privileged or stale information into the broader list
+call it was unreachable for.
+
 ### Using request field to opt-in
 
 Introducing a new request field as means of opting into the partial success
@@ -182,6 +227,8 @@ requests that cannot be fulfilled preemptively.
 
 ## Changelog
 
+- **2024-07-29**: Reformat guidance, add explicit resource name format
+  requirement.
 - **2024-07-19**: Add guidance for brownfield adoption of partial success.
 
 [aip-159]: ./0159.md