Clean up AIP-136: Custom methods. (#103)

* Clean up AIP-136: Custom methods.

This is in preparation for the barn raising event, and makes the AEP more consistent with more recently-adopted AEPs.  Common guidance is also factored out of the IDL-specific tabs.

I added one new bullet point of guidance while I was at it.  I doubt this will be controversial, but calling it out for completeness.

I actually think most of the changes from the Google AIP are pretty good in this case, so I have generally not modified them.

* Update creation date

* Update aep/general/0136/aep.md.j2

Co-authored-by: Yusuke Tsutsumi <yusuke@tsutsumi.io>

* Update aep/general/0136/aep.md.j2

Co-authored-by: Yusuke Tsutsumi <yusuke@tsutsumi.io>

* Address PR comments

---------

Co-authored-by: Yusuke Tsutsumi <yusuke@tsutsumi.io>

Author: rofrankel

aep/general/0136/aep.md.j2

@@ -1,76 +1,84 @@
-# Custom operations
+# Custom methods
 
-Services use custom operations to provide a means to express arbitrary actions
-that are difficult to model using only the standard operations. Custom
-operations are important because they provide a means for an API's vocabulary
-to adhere to user intent.
+Resource oriented design (AEP-121) uses custom methods to provide a means to
+express actions that are difficult to model using only the standard methods.
+Custom methods are important because they provide a means for an API's
+vocabulary to adhere to user intent.
 
 ## Guidance
 
-Custom operations **should** only be used for functionality that can not be
-easily expressed via standard operations; prefer standard operations if
-possible, due to their consistent semantics. (Of course, this only applies if
-the functionality in question actually conforms to the normal semantics; it is
-_not_ a good idea to contort things to endeavor to make the standard operations
-"sort of work".)
+Custom methods **should** only be used for functionality that can not be
+expressed via standard methods; prefer standard methods if possible, due to
+their consistent semantics. However, APIs **should not** contort things to
+endeavor to make the standard methods "sort of work".
 
-While custom operations vary widely in how they are designed, many principles
+While custom methods vary widely in how they are designed, many principles
 apply consistently:
 
+- The HTTP method for custom methods **should** be selected based on the
+  semantics described by [RFC 7231 section 4.3] and [RFC 5789] for `PATCH`. In
+  practice, the vast majority of custom methods **should** use `POST` or `GET`.
+  - Custom methods that serve as an alternative to get or list methods (such as
+    `Search`) **should** use `GET`, and require no request body. These methods
+    **must** be idempotent and have no state changes or side effects (they
+    should be safe as defined in [RFC 7231 section 4.2.1][]).
+  - Custom methods **should not** use `PATCH` or `DELETE`.
+- 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.
+
 {% tab proto %}
 
 {% sample 'library.proto', 'rpc ArchiveBook' %}
 
 - The name of the RPC **should** be a verb followed by a noun.
   - The name **must not** contain prepositions ("for", "with", etc.).
-- The HTTP method for custom operations **should** usually be `POST`, unless
-  the custom method maps more strongly to another HTTP verb.
-  - Custom operations that serve as an alternative to get or list operations
-    (such as `Search`) **should** use `GET`. These operations **must** be
-    idempotent and have no state changes or side effects (they should be safe
-    as defined in [RFC 7231][]).
-  - Custom operations **should not** use `PATCH` or `DELETE`.
-- 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 operations **should** usually take a request message matching the RPC
-  name, with a -`Request` suffix.
-- Custom operations **should** usually return a response message matching the
-  RPC name, with a -`Response` suffix.
+- Custom methods **must** take a request message exactly matching the RPC name,
+  with a `Request` suffix. For example, `ArchiveBookRequest`.
+- Custom methods **should** return a response message exactly matching the RPC
+  name, with a `Response` suffix. For example, `ArchiveBookResponse`.
   - When operating on a specific resource, a custom method **may** return the
     resource itself.
 
 {% tab oas %}
 
 {% sample 'library.oas.yaml', '/publishers/{publisherId}/books/{bookId}:archive' %}
 
-- The `operationId` **should** be a verb followed by a noun.
-  - The `operationId` **must not** contain prepositions ("for", "with", etc.).
-- The HTTP method for custom operations **should** usually be `POST`, unless
-  the custom method maps more strongly to another HTTP verb.
-  - Custom operations that serve as an alternative to get or list operations
-    (such as `Search`) **should** use `GET`, and require no request body. These
-    operations **must** be idempotent and have no state changes or side effects
-    (they should be safe as defined in [RFC 7231][]).
-  - Custom operations **should not** use `PATCH` or `DELETE`.
-- 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 `operationId`.
-  - If word separation is required, `camelCase` **must** be used.
+- The name of the RPC **should** be a verb followed by a noun.
+  - The name of the RPC **must not** contain prepositions ("for", "with",
+    etc.).
 
 {% endtabs %}
 
 **Note:** The pattern above shows a custom method that operates on a specific
-resource. Custom operations can be associated with resources, collections, or
+resource. Custom methods can be associated with resources, collections, or
 services.
 
-### Collection-based custom operations
+### Resource-based custom methods
+
+Custom methods **must** operate on a resource if the API can be modeled as
+such:
+
+{% tab proto %}
+
+{% sample 'library.proto', 'rpc ArchiveBook' %}
+
+- The parameter for the resource's path **must** be called `path`, and **must**
+  be the only variable in the URI path.
+
+{% tab oas %}
+
+**Note:** OAS example not yet written.
+
+{% endtabs %}
+
+### Collection-based custom methods
 
-While most custom operations operate on a single resource, some custom
-operations **may** operate on a collection instead:
+While most custom methods operate on a single resource, some custom methods
+**may** operate on a collection instead:
 
 {% tab proto %}
 
@@ -83,15 +91,14 @@ operations **may** operate on a collection instead:
 {% endtabs %}
 
 - 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.
+  **should** be `parent`.
 - The collection key (`books` in the above example) **must** be literal.
 
-### Stateless operations
+### Stateless methods
 
-Some custom operations are not attached to resources at all. These operations
-are generally _stateless_: they accept a request and return a response, and
-have no permanent effect on data within the API.
+Some custom methods are not attached to resources at all. These methods are
+generally _stateless_: they accept a request and return a response, and have no
+permanent effect on data within the API.
 
 {% tab proto %}
 
@@ -110,17 +117,21 @@ have no permanent effect on data within the API.
 - The URI **should** place both the verb and noun after the `:` separator
   (avoid a "faux collection key" in the URI in this case, as there is no
   collection). For example, `:translateText` is preferable to `text:translate`.
-- Stateless operations **must** use `POST` if they involve billing.
+- Stateless methods **must** use `POST` if they involve billing.
 
 ### Declarative-friendly resources
 
-Declarative-friendly resources usually **should not** employ custom operations
-(except specific declarative-friendly custom operations discussed in other
-AEPs), because declarative-friendly tools are unable to automatically determine
-what to do with them.
+Declarative-friendly resources usually **should not** employ custom methods
+(except specific declarative-friendly custom methods discussed in other AEPs),
+because declarative-friendly tools are unable to automatically determine what
+to do with them.
 
 An exception to this is for rarely-used, fundamentally imperative operations,
 such as a `Move`, `Rename`, or `Restart` operation, for which there would not
 be an expectation of declarative support.
 
-[rfc 7231]: https://datatracker.ietf.org/doc/html/rfc7231#section-4.2.1
+<!-- prettier-ignore-start -->
+[rfc 5789]: https://datatracker.ietf.org/doc/html/rfc5789
+[rfc 7231 section 4.2.1]: https://datatracker.ietf.org/doc/html/rfc7231#section-4.2.1
+[rfc 7231 section 4.3]: https://datatracker.ietf.org/doc/html/rfc7231#section-4.3
+<!-- prettier-ignore-end -->

aep/general/0136/aep.yaml

@@ -3,6 +3,7 @@ id: 136
 state: approved
 slug: custom-methods
 created: 2019-01-25
+updated: 2024-03-08
 placement:
   category: standard-methods
   order: 100

aep/general/0136/library.proto

@@ -23,24 +23,24 @@ service Library {
   // Archives the given book.
   rpc ArchiveBook(ArchiveBookRequest) returns (ArchiveBookResponse) {
     option (google.api.http) = {
-      post: "/v1/{name=publishers/*/books/*}:archive"
+      post: "/v1/{path=publishers/*/books/*}:archive"
       body: "*"
     };
   }
 
   // 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: "*"
     };
   }
 }
 
 // Request message to archive a book.
 message ArchiveBookRequest {
-  // The name of the book to retrieve.
-  string name = 1 [
+  // The path of the book to retrieve.
+  string path = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {
       type: "library.googleapis.com/Book"
@@ -59,8 +59,8 @@ message ArchiveBookResponse {
 
 // Request message to sort a collection of books.
 message SortBooksRequest {
-  // The name of the publisher to sort books for.
-  string publisher = 1 [
+  // The path of the publisher to sort books for.
+  string parent = 1 [
     (google.api.field_behavior) = REQUIRED,
     (google.api.resource_reference) = {
       type: "library.googleapis.com/Publisher"
@@ -81,9 +81,9 @@ message Book {
     pattern: "publishers/{publisher}/books/{book}"
   };
 
-  // The name of the book.
+  // The path of the book.
   // Format: publishers/{publisher}/books/{book}
-  string name = 1;
+  string path = 1;
 
   // The ISBN (International Standard Book Number) for this book.
   string isbn = 2;