feat(AIP-136): require GET/POST, use parent instead of singular (#1093)

The resource singular is a harder pattern to recognize as it
requires a consumer to know the resource singular beforehand. Using
parent aligns it with other collection-oriented methods.

Further explanation for the rationale is in the changes for AIP-136.

fixes #1089

Author: toumorokoshi

aip/general/0136.md

@@ -44,25 +44,42 @@ services. The bullets below apply in all three cases.
   - The name **must not** contain prepositions ("for", "with", etc.).
   - The verb in the name **should not** contain any of the standard method verbs ([Get][],
     [List][], [Create][], [Update][], [Delete][]).
-- The HTTP method for custom methods **should** usually be `POST`, unless the
-  custom method maps more strongly to another HTTP verb.
-  - Custom methods that serve as an alternative to get or list methods (such as
-    `Search`) **should** use `GET`. These methods **must** be idempotent and
-    have no side effects.
-  - Custom methods **should not** use `PATCH` or `DELETE`.
+- The HTTP method **must** be `GET` or `POST`:
+  - `GET` **must** be used for methods retrieving data or resource state.
+  - `POST` **must** be used if the method has side effects or mutates resources
+    or data.
 - The HTTP URI **must** use a `:` character followed by the custom verb
   (`:archive` in the above example), and the verb in the URI **must** match the
   verb in the name of the RPC.
   - If word separation is required, `camelCase` **must** be used.
 - The `body` clause in the `google.api.http` annotation **should** be `"*"`.
-  - However, if using `GET` or `DELETE`, the `body` clause **must** be absent.
-- Custom methods **should** usually take a request message matching the RPC
+  - However, if using `GET`, the `body` clause **must** be absent.
+- Custom methods **should** take a request message matching the RPC
   name, with a `Request` suffix.
-- Custom methods **should** usually return a response message matching the RPC
+- Custom methods **should** return a response message matching the RPC
   name, with a `Response` suffix.
   - When operating on a specific resource, a custom method **may** return the
     resource itself.
 
+
+### Resource-based custom methods
+
+Custom methods **must** operate on a resource if the API can be modeled
+as such:
+
+```proto
+// Archives the given book.
+rpc ArchiveBook(ArchiveBookRequest) returns (ArchiveBookResponse) {
+  option (google.api.http) = {
+    post: "/v1/{name=publishers/*/books/*}:archive"
+    body: "*"
+  };
+}
+```
+
+- The parameter for the resource's name **must** be called `name`, and
+  be the only variable in the URI path.
+
 ### Collection-based custom methods
 
 While most custom methods operate on a single resource, some custom methods
@@ -72,15 +89,14 @@ While most custom methods operate on a single resource, some custom methods
 // Sorts the books from this publisher.
 rpc SortBooks(SortBooksRequest) returns (SortBooksResponse) {
   option (google.api.http) = {
-    post: "/v1/{publisher=publishers/*}/books:sort"
+    post: "/v1/{parent=publishers/*}/books:sort"
     body: "*"
   };
 }
 ```
 
-- If the collection has a parent, the field name in the request message
-  **should** be the target resource's singular noun (`publisher` in the above
-  example). If word separators are necessary, `snake_case` **must** be used.
+- The collection's parent resource **must** be called `parent`, and
+  be the only variable in the URI path.
 - The collection key (`books` in the above example) **must** be literal.
 
 ### Stateless methods
@@ -119,6 +135,24 @@ An exception to this is for rarely-used, fundamentally imperative operations,
 such as a `Move` or `Rename` operation, for which there would not be an
 expectation of declarative support.
 
+## Rationale
+
+### HTTP path
+
+Similar to standard methods, a custom method that operates on a resource or
+collection needs a `name` or `parent` parameter to indicate the resource that it
+operates on. This convention allows clients to map custom methods to the
+appropriate resource.
+
+### HTTP methods
+
+Allowing both `GET` and `POST` HTTP verbs allows a clear distinction for
+which methods do not mutate data, and which ones do. Methods that only
+read data have first-class concepts in some clients (DataSources in
+Terraform) and clearly indicate to a user which methods can be called
+without risk of runtime impact.
+
+
 [get]: ./0131.md
 [list]: ./0132.md
 [create]: ./0133.md
@@ -127,6 +161,8 @@ expectation of declarative support.
 
 ## Changelog
 
+- **2023-05-09:** Adding guidance for POST and GET, require parent instead of
+  the resource singular.
 - **2023-03-02:** Explicitly discourage use of standard method verbs.
 - **2022-06-02:** Changed suffix descriptions to eliminate superfluous "-".
 - **2020-10-06:** Added declarative-friendly guidance.