feat(AIP-156): support Standard List (#1195)

Author: noahdietz

aip/general/0156.md

@@ -53,20 +53,64 @@ rpc UpdateConfig(UpdateConfigRequest) returns (Config) {
   their [resource name][aip-122] includes the name of their parent followed by
   one static-segment.
   - Example: `users/1234/config`
-- Singleton resources **must not** define the [`Create`][aip-133],
-  [`List`][aip-132], or [`Delete`][aip-135] standard methods. The singleton is
-  implicitly created or deleted when its parent is created or deleted.
+- Singleton resources are always singular.
+  - Example: `users/1234/thing`
+- Singleton resources **may** parent other resources.
+- Singleton resources **must not** define the [`Create`][aip-133] or
+  [`Delete`][aip-135] standard methods. The singleton is implicitly created or
+  deleted when its parent is created or deleted.
 - Singleton resources **should** define the [`Get`][aip-131] and
   [`Update`][aip-134] methods, and **may** define custom methods as
   appropriate.
   - However, singleton resources **must not** define the [`Update`][aip-134]
     method if all fields on the resource are [output only][aip-203].
-- Singleton resources are always singular.
-  - Example: `users/1234/thing`
-- Singleton resources **may** parent other resources.
+- Singleton resources **may** define the [`List`][aip-132] method, but **must**
+  implement it according to [AIP-159][aip-159]. See the example below.
+  - The trailing segment in the path pattern that typically represents the 
+    collection **should** be the `plural` form of the Singleton resource e.g.
+    `/v1/{parent=users/*}/configs`.
+  - If a parent resource ID is provided instead of the hyphen `-` as per
+    AIP-159, then the service **should** return a collection of one Singleton
+    resource corresponding to the specified parent resource.
+
+```proto
+rpc ListConfigs(ListConfigsRequest) returns (ListConfigsResponse) {
+  option (google.api.http) = {
+    get: "/v1/{parent=users/*}/configs"
+  };
+}
+
+message ListConfigsRequest {
+  // To list all configs, use `-` as the user id.
+  // Formats:
+  // * `users/-`
+  // * `users/{user}`
+  //
+  // Note: Specifying an actual user id will return a collection of one config.
+  // Use GetConfig instead.
+  string parent = 1 [
+    (google.api.resource_reference).child_type = "api.googleapis.com/Config"];
+
+  // other standard pagination fields...
+}
+```
+## Rationale
+
+### Support for Standard List
+
+While Singleton resources are not directly part of a collection themselves, they
+can be viewed as part of their parent's collection. The one-to-one relationship
+of parent-to-singleton means that for every one parent there is one singleton
+instance, naturally enabling some collection-based methods when combined with
+the pattern of [Reading Across Collections][aip-159]. The Singleton can present
+as a collection to the API consumer as it is indirectly one based on its parent.
+Furthermore, presenting the Singleton resource as a pseudo-collection in such
+methods enables future expansion to a real collection, should a Singleton be
+found lacking.
 
 ## Changelog
 
+- **2023-08-10:** Add Standard `List` support.
 - **2023-07-26:** Clarified that read-only singletons should not have `Update`.
 - **2021-11-02:** Added an example message and state parent eligibility.
 - **2021-01-14:** Changed example from `settings` to `config` for clarity.
@@ -77,4 +121,5 @@ rpc UpdateConfig(UpdateConfigRequest) returns (Config) {
 [aip-133]: ./0133.md
 [aip-134]: ./0134.md
 [aip-135]: ./0135.md
+[aip-159]: ./0159.md
 [aip-203]: ./0203.md#output-only