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

aip/general/0136.md

@@ -44,12 +44,10 @@ 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 `POST` if the method mutates
+ reosurces or data, and **must** be `GET` otherwise.
+- The parameter for the resource's name **must** be called `name`, and
+ be the only variable in the URI path.
 - 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.
@@ -72,15 +70,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
+ **should** be the only variable in the URI path.
 - The collection key (`books` in the above example) **must** be literal.
 
 ### Stateless methods
@@ -119,6 +116,23 @@ 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 should have a `name` or `parent`
+parameter to indicate the resource that it is associated with. Following 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 riskof runtime impact.
+
+
 [get]: ./0131.md
 [list]: ./0132.md
 [create]: ./0133.md
@@ -127,6 +141,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.