Fix the descriptions of suffix to be more precise (aip-dev#903)

* Make the description of suffix use more precise

The existing suffix descriptions of "-Request" or "-Response" aren't quite accurate: the required suffix is simply "Request" or "Response". Including the "-" in the description is superfluous, as it is already clearly described as a "suffix", and potentially confusing as the reader could understand the "-Request" or "-Response" to be verbatim and inconsistent with the examples. (Also note that later in this doc the ":" symbol is given to be verbatim.)

* add changelog item

* add updated field to header

* remove "-" from all Request and Response suffixes

aip/general/0131.md

@@ -2,6 +2,7 @@
 id: 131
 state: approved
 created: 2019-01-22
+updated: 2022-06-02
 placement:
   category: operations
   order: 10
@@ -36,7 +37,7 @@ rpc GetBook(GetBookRequest) returns (Book) {
 
 - The RPC's name **must** begin with the word `Get`. The remainder of the RPC
   name **should** be the singular form of the resource's message name.
-- The request message **must** match the RPC name, with a `-Request` suffix.
+- The request message **must** match the RPC name, with a `Request` suffix.
 - The response message **must** be the resource itself. (There is no
   `GetBookResponse`.)
   - The response **should** usually include the fully-populated resource unless
@@ -99,6 +100,7 @@ exist, the service **must** error with `NOT_FOUND` (HTTP 404).
 
 ## Changelog
 
+- **2022-06-02:** Changed suffix descriptions to eliminate superfluous "-".
 - **2020-06-08**: Added guidance on returning the full resource.
 - **2019-10-18**: Added guidance on annotations.
 - **2019-08-12**: Added guidance for error cases.

aip/general/0132.md

@@ -2,6 +2,7 @@
 id: 132
 state: approved
 created: 2019-01-21
+updated: 2022-06-02
 placement:
   category: operations
   order: 20
@@ -37,7 +38,7 @@ rpc ListBooks(ListBooksRequest) returns (ListBooksResponse) {
 - The RPC's name **must** begin with the word `List`. The remainder of the RPC
   name **should** be the plural form of the resource being listed.
 - The request and response messages **must** match the RPC name, with
-  `-Request` and `-Response` suffixes.
+  `Request` and `Response` suffixes.
 - The HTTP verb **must** be `GET`.
 - The collection whose resources are being listed **should** map to the URI
   path.
@@ -204,6 +205,7 @@ not exist, the service **must** error with `NOT_FOUND` (HTTP 404).
 
 ## Changelog
 
+- **2022-06-02:** Changed suffix descriptions to eliminate superfluous "-".
 - **2020-09-02**: Add link to the filtering AIP.
 - **2020-08-14**: Added error guidance for permission denied cases.
 - **2020-06-08**: Added guidance on returning the full resource.

aip/general/0133.md

@@ -2,6 +2,7 @@
 id: 133
 state: approved
 created: 2019-01-23
+updated: 2022-06-02
 placement:
   category: operations
   order: 30
@@ -37,7 +38,7 @@ rpc CreateBook(CreateBookRequest) returns (Book) {
 
 - The RPC's name **must** begin with the word `Create`. The remainder of the
   RPC name **should** be the singular form of the resource being created.
-- The request message **must** match the RPC name, with a `-Request` suffix.
+- The request message **must** match the RPC name, with a `Request` suffix.
 - The response message **must** be the resource itself. There is no
   `CreateBookResponse`.
   - The response **should** include the fully-populated resource, and **must**
@@ -194,6 +195,7 @@ user-specified IDs.
 
 ## Changelog
 
+- **2022-06-02:** Changed suffix descriptions to eliminate superfluous "-".
 - **2020-10-06**: Added declarative-friendly guidance.
 - **2020-08-14**: Updated error guidance to use permission denied over
   forbidden.

aip/general/0134.md

@@ -2,6 +2,7 @@
 id: 134
 state: approved
 created: 2019-01-24
+updated: 2022-06-02
 placement:
   category: operations
   order: 40
@@ -37,7 +38,7 @@ rpc UpdateBook(UpdateBookRequest) returns (Book) {
 
 - The RPC's name **must** begin with the word `Update`. The remainder of the
   RPC name **should** be the singular form of the resource's message name.
-- The request message **must** match the RPC name, with a `-Request` suffix.
+- The request message **must** match the RPC name, with a `Request` suffix.
 - The response message **must** be the resource itself. (There is no
   `UpdateBookResponse`.)
   - The response **should** include the fully-populated resource, and **must**
@@ -283,6 +284,7 @@ exist, the service **must** error with `NOT_FOUND` (HTTP 404) unless
 
 ## Changelog
 
+- **2022-06-02:** Changed suffix descriptions to eliminate superfluous "-".
 - **2021-11-04**: Changed the permission check if `allow_missing` is set.
 - **2021-07-08**: Added error guidance for resource not found case.
 - **2021-03-05**: Changed the etag error from `FAILED_PRECONDITION` (which

aip/general/0135.md

@@ -2,6 +2,7 @@
 id: 135
 state: approved
 created: 2019-01-24
+updated: 2022-06-02
 placement:
   category: operations
   order: 50
@@ -35,7 +36,7 @@ rpc DeleteBook(DeleteBookRequest) returns (google.protobuf.Empty) {
 
 - The RPC's name **must** begin with the word `Delete`. The remainder of the
   RPC name **should** be the singular form of the resource's message name.
-- The request message **must** match the RPC name, with a `-Request` suffix.
+- The request message **must** match the RPC name, with a `Request` suffix.
 - The response message **should** be `google.protobuf.Empty`.
   - If the resource is [soft deleted](#soft-delete), the response message
     **should** be the resource itself.
@@ -233,6 +234,7 @@ exist, the service **must** error with `NOT_FOUND` (HTTP 404) unless
 
 ## Changelog
 
+- **2022-06-02:** Changed suffix descriptions to eliminate superfluous "-".
 - **2022-02-02**: Changed eTag error from `FAILED_PRECONDITION` to `ABORTED` making it consistent with change to [AIP-154][] & [AIP-134][etag] on 2021-03-05.
 - **2020-10-06**: Added guidance for declarative-friendly resources.
 - **2020-10-06**: Added guidance for allowing no-op delete for missing

aip/general/0136.md

@@ -2,6 +2,7 @@
 id: 136
 state: approved
 created: 2019-01-25
+updated: 2022-06-02
 placement:
   category: operations
   order: 100
@@ -54,9 +55,9 @@ services. The bullets below apply in all three cases.
 - 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
-  name, with a `-Request` suffix.
+  name, with a `Request` suffix.
 - Custom methods **should** usually return a response message matching the RPC
-  name, with a `-Response` suffix.
+  name, with a `Response` suffix.
   - When operating on a specific resource, a custom method **may** return the
     resource itself.
 
@@ -118,6 +119,7 @@ expectation of declarative support.
 
 ## Changelog
 
+- **2022-06-02:** Changed suffix descriptions to eliminate superfluous "-".
 - **2020-10-06:** Added declarative-friendly guidance.
 - **2019-08-01:** Changed the examples from "shelves" to "publishers", to
   present a better example of resource ownership.

aip/general/0144.md

@@ -2,6 +2,7 @@
 id: 144
 state: approved
 created: 2020-03-19
+updated: 2022-06-02
 placement:
   category: fields
   order: 50
@@ -95,10 +96,10 @@ rpc RemoveAuthor(RemoveAuthorRequest) returns (Book) {
     a map with the `Update` method instead.
 - The RPC's name **must** begin with the word `Add` or `Remove`. The remainder
   of the RPC name **should** be the singular form of the field being added.
-- The request message **must** match the RPC name, with a `-Request` suffix.
+- The request message **must** match the RPC name, with a `Request` suffix.
 - The response message **should** be the resource itself, unless there is useful
   context to provide in the response, in which case the response message must
-  match the RPC name, with a `-Response` suffix.
+  match the RPC name, with a `Response` suffix.
   - When the response is the resource itself, it **should** include the
     fully-populated resource.
 - The HTTP verb **must** be `POST`, as is usual for [custom methods][aip-136].
@@ -153,6 +154,7 @@ message RemoveAuthorRequest {
 
 ## Changelog
 
+- **2022-06-02:** Changed suffix descriptions to eliminate superfluous "-".
 - **2020-10-17**: Recommended returning the resource itself in Add and Remove
   RPCs over separate response types.
 - **2020-10-17**: Added guidance for Add and Remove RPCs and requests.

aip/general/0152.md

@@ -2,6 +2,7 @@
 id: 152
 state: approved
 created: 2020-04-27
+updated: 2022-06-02
 placement:
   category: design-patterns
   order: 10
@@ -58,11 +59,11 @@ rpc RunWriteBookJob(RunWriteBookJobRequest)
 
 - The RPC's name **must** begin with the word `Run`. The remainder of the
   RPC name **should** be the singular form of the job resource being run.
-- The request message **must** match the RPC name, with a `-Request` suffix.
+- The request message **must** match the RPC name, with a `Request` suffix.
 - The method **should** return a [long-running operation][aip-151], which
   **must** resolve to a response message that includes the result of running
   the job.
-  - The response message name must match the RPC name, with a `-Response`
+  - The response message name must match the RPC name, with a `Response`
     suffix.
   - The method **may** use any metadata message it wishes.
 - The HTTP verb **must** be `POST`, as is usual for [custom methods][aip-136].
@@ -127,6 +128,7 @@ the child resource.
 
 ## Changelog
 
+- **2022-06-02:** Changed suffix descriptions to eliminate superfluous "-".
 - **2020-11-02**: Expanded guidance on HTTP, field behavior, and resource
   reference annotations and request format.
 

aip/general/0165.md

@@ -2,6 +2,7 @@
 id: 165
 state: approved
 created: 2019-12-18
+updated: 2022-06-02
 placement:
   category: design-patterns
   order: 100
@@ -45,10 +46,10 @@ rpc PurgeBooks(PurgeBooksRequest) returns (google.longrunning.Operation) {
 
 - The RPC's name **must** begin with the word `Purge`. The remainder of the
   RPC name **should** be the plural form of the resource being purged.
-- The request message **must** match the RPC name, with a `-Request` suffix.
+- The request message **must** match the RPC name, with a `Request` suffix.
 - The response type **must** be a `google.longrunning.Operation` (see
   AIP-151) that resolves to a message whose name matches the RPC name, with
-  a `-Response` suffix.
+  a `Response` suffix.
 - The HTTP verb **must** be `POST`, and the `body` **must** be `"*"`.
 - The URI path **should** represent the collection for the resource.
 - The `parent` field **should** be included in the URI. If the API wishes to
@@ -131,6 +132,7 @@ message PurgeBooksResponse {
 
 ## Changelog
 
+- **2022-06-02:** Changed suffix descriptions to eliminate superfluous "-".
 - **2020-10-29**: Expanded guidance on HTTP, field behavior, and resource
   reference annotations.
 

aip/general/0216.md

@@ -2,6 +2,7 @@
 id: 216
 state: approved
 created: 2018-10-01
+updated: 2022-06-02
 placement:
   category: fields
   order: 110
@@ -89,7 +90,7 @@ rpc PublishBook(PublishBookRequest) returns (Book) {
 
 - The name of the method **should** be a verb followed by the singular form of
   the resource's message name.
-- The request message **must** match the RPC name, with a `-Request` suffix.
+- The request message **must** match the RPC name, with a `Request` suffix.
 - The response message **should** be the resource itself.
   - If the RPC is [long-running][], the response message **should** be a
     `google.longrunning.Operation` which resolves to the resource itself.
@@ -232,6 +233,7 @@ necessary.
 
 ## Changelog
 
+- **2022-06-02:** Changed suffix descriptions to eliminate superfluous "-".
 - **2020-10-20**: Added guidance on prefixing enum values with enum name.
 - **2020-09-02**: Clarified that states are not directly set on create either.
 - **2019-12-05**: Changed guidance on state transition methods, downgrading

aip/general/0231.md

@@ -2,6 +2,7 @@
 id: 231
 state: approved
 created: 2019-06-18
+updated: 2022-06-02
 placement:
   category: operations
   order: 200
@@ -28,7 +29,7 @@ rpc BatchGetBooks(BatchGetBooksRequest) returns (BatchGetBooksResponse) {
 - The RPC's name **must** begin with `BatchGet`. The remainder of the RPC name
   **should** be the plural form of the resource being retrieved.
 - The request and response messages **must** match the RPC name, with
-  `-Request` and `-Response` suffixes.
+  `Request` and `Response` suffixes.
 - The HTTP verb **must** be `GET`.
 - The HTTP URI **must** end with `:batchGet`.
 - The URI path **should** represent the collection for the resource, matching
@@ -179,6 +180,7 @@ message BatchGetBooksRequest {
 
 ## Changelog
 
+- **2022-06-02:** Changed suffix descriptions to eliminate superfluous "-".
 - **2020-09-16**: Suggested annotating `parent`, `names`, and `requests` fields.
 - **2020-08-27**: Removed parent recommendations for top-level resources.
 - **2020-03-24**: Clarified behavior if no resource names are sent.

aip/general/0233.md

@@ -2,6 +2,7 @@
 id: 233
 state: approved
 created: 2019-06-18
+updated: 2022-06-02
 placement:
   category: operations
   order: 210
@@ -28,10 +29,10 @@ rpc BatchCreateBooks(BatchCreateBooksRequest) returns (BatchCreateBooksResponse)
 - The RPC's name **must** begin with `BatchCreate`. The remainder of the RPC
   name **should** be the plural form of the resource being created.
 - The request and response messages **must** match the RPC name, with
-  `-Request` and `-Response` suffixes.
+  `Request` and `Response` suffixes.
   - However, in the event that the request may take a significant amount of
     time, the response message **must** be a `google.longrunning.Operation`
-    which ultimately resolves to the `-Response` type.
+    which ultimately resolves to the `Response` type.
 - The HTTP verb **must** be `POST`.
 - The HTTP URI **must** end with `:batchCreate`.
 - The URI path **should** represent the collection for the resource, matching
@@ -113,6 +114,7 @@ message BatchCreateBooksResponse {
 
 ## Changelog
 
+- **2022-06-02:** Changed suffix descriptions to eliminate superfluous "-".
 - **2020-09-16**: Suggested annotating `parent` and `requests` fields.
 - **2020-08-27**: Removed parent recommendations for top-level resources.
 - **2019-08-01**: Changed the examples from "shelves" to "publishers", to

aip/general/0234.md

@@ -2,6 +2,7 @@
 id: 234
 state: approved
 created: 2019-06-18
+updated: 2022-06-02
 placement:
   category: operations
   order: 220
@@ -28,10 +29,10 @@ rpc BatchUpdateBooks(BatchUpdateBooksRequest) returns (BatchUpdateBooksResponse)
 - The RPC's name **must** begin with `BatchUpdate`. The remainder of the RPC
   name **should** be the plural form of the resource being updated.
 - The request and response messages **must** match the RPC name, with
-  `-Request` and `-Response` suffixes.
+  `Request` and `Response` suffixes.
   - However, in the event that the request may take a significant amount of
     time, the response message **must** be a `google.longrunning.Operation`
-    which ultimately resolves to the `-Response` type.
+    which ultimately resolves to the `Response` type.
 - The HTTP verb **must** be `POST`.
 - The HTTP URI **must** end with `:batchUpdate`.
 - The URI path **should** represent the collection for the resource, matching
@@ -111,6 +112,7 @@ message BatchUpdateBooksResponse {
 
 ## Changelog
 
+- **2022-06-02:** Changed suffix descriptions to eliminate superfluous "-".
 - **2020-09-16**: Suggested annotating `parent` and `requests` fields.
 - **2020-08-27**: Removed parent recommendations for top-level resources.
 - **2019-09-11**: Fixed the wording about which child field the `parent` field

aip/general/0235.md

@@ -2,6 +2,7 @@
 id: 235
 state: approved
 created: 2019-06-18
+updated: 2022-06-02
 placement:
   category: operations
   order: 230
@@ -27,7 +28,7 @@ rpc BatchDeleteBooks(BatchDeleteBooksRequest) returns (google.protobuf.Empty) {
 
 - The RPC's name **must** begin with `BatchDelete`. The remainder of the RPC
   name **should** be the plural form of the resource being deleted.
-- The request message **must** match the RPC name, with a `-Request` suffix.
+- The request message **must** match the RPC name, with a `Request` suffix.
 - The response message **should** be `google.protobuf.Empty`.
   - If the resource is [soft deleted][soft-delete], the response message
     **should** be a response message containing the updated resources.
@@ -177,6 +178,7 @@ message BatchDeleteBooksResponse {
 
 ## Changelog
 
+- **2022-06-02:** Changed suffix descriptions to eliminate superfluous "-".
 - **2020-09-16**: Suggested annotating `parent`, `names`, and `requests` fields.
 - **2020-08-27**: Removed parent recommendations for top-level resources.
 - **2020-03-27**: Added reference to AIP-165 for criteria-based deletion.