Default field_mask value and deprecate on request. (#853)

* Default value and deprecate on request.

Explicitly document default value for field mask. Deprecate field mask on request.

* Removed recommended/deprecated from headings.

* jskeet suggestions

Author: alin04

aip/general/0157.md

@@ -14,27 +14,26 @@ needs to give the user control over which fields it sends back.
 
 ## Guidance
 
-APIs **may** support partial responses in one of the three ways:
+APIs **may** support partial responses in one of two ways:
 
 ### Field masks parameter
 
 Field masks (`google.protobuf.FieldMask`) can be used for granting the user
-fine-grained control over what fields are returned. It is generally the
-recommended way for an API to support partial responses.
+fine-grained control over what fields are returned. An API **should** support the mask in a side channel.
+For example, the parameter can be specified either using an HTTP query
+parameter, an HTTP header, or a [gRPC metadata entry][1]. Google Cloud APIs specify field masks as a [system parameter][0].
 
-To enable field masks, an API **should** support the masks as a [system parameter][0].
-This parameter can be specified either using an HTTP query
-parameter or an HTTP header (or a [gRPC metadata entry][1]).
+Field masks **should not** be specified in the [request](./0157.md#read-masks-as-a-request-field).
 
 - The value of the field mask parameter **must** be a `google.protobuf.FieldMask`.
-- The field mask parameter **should** be specified using `$field` as a query parameter or `X-Goog-FieldMask` as an HTTP header.
 - The field mask parameter **must** be optional:
   - An explicit value of `"*"` **should** be supported, and **must** return all
     fields.
-  - If the field mask parameter is not provided, all fields **must** be
-    returned.
+  - If the field mask parameter is omitted, it **must** default to `"*"`, unless otherwise documented.
 - An API **may** allow read masks with non-terminal repeated fields (unlike
   update masks), but is not obligated to do so.
+  
+**Note:** Changing the default value of the field mask parameter is a [breaking change](../0180.md#semantic-changes).
 
 ### View enumeration
 
@@ -78,21 +77,11 @@ enum BookView {
 
 ### Read masks as a request field
 
-Similar to a system parameter, an API **may** support read masks as a single field on the request
-message: `google.protobuf.FieldMask read_mask`.
-
-- The read mask **must** be a `google.protobuf.FieldMask` and **should** be
-  named `read_mask`.
-- The field mask **should** be optional:
-  - An explicit value of `"*"` **should** be supported, and **must** return all
-    fields.
-  - If the field mask parameter is not provided, all fields **must** be
-    returned.
-- An API **may** allow read masks with non-terminal repeated fields (unlike
-  update masks), but is not obligated to do so.
+**Warning:** Read masks as a single field on the request message, for example: `google.protobuf.FieldMask read_mask` are **DEPRECATED**.
 
 ## Changelog
 
+- **2022-03-14:** Updated guidance on default value and how to specify a read mask.
 - **2021-10-06:** Updated the guidance with system parameters.
 - **2021-03-04:** Added guidance for conflicting view enums.