Adopt Google's AIP-134: Update (#115)

* Make 0134/aep.md a jinja2 template.

* Copy/paste the Google Update AIP verbatim.

* De-Google

* A variety of small updates:

* Put proto-specific content in tabs, with placeholder OAS tabs.
* Remove LRO guidannce that is redundant with the LRO AEP.
* Change a small number of **should**s to **must**s.
* Light copy-editing.

* AIP -> AEP

* Reviewing -> Approved

* Remove redundant header.

* Fix link text

* Fix tab location

* Restore LRO section for consistency.

* Remove redundant guidance about including path field on resource.

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

Co-authored-by: Mike Kistler <mkistler@sbcglobal.net>

* De-protofy generic guidance a bit.

---------

Co-authored-by: Mike Kistler <mkistler@sbcglobal.net>

Author: rofrankel

aep/general/0134/aep.md

@@ -0,0 +1,319 @@
+# Update
+
+In REST APIs, it is customary to make a `PATCH` or `PUT` request to a
+resource's URI (for example, `/v1/publishers/{publisher}/books/{book}`) in
+order to update that resource.
+
+Resource-oriented design (AEP-121) honors this pattern through the `Update`
+method (which mirrors the REST `PATCH` behavior). These methods accept the URI
+representing that resource and return the resource.
+
+## Guidance
+
+APIs **should** provide an update method for resources unless it is not
+valuable for users to do so. The purpose of the update method is to make
+changes to the resources without causing side effects.
+
+Update methods are specified using the following pattern:
+
+- The method's name **must** begin with the word `Update`. The remainder of the
+  method name **should** be the singular form of the resource's name.
+- The request schema's name **must** exactly match the RPC name, with a
+  `Request` suffix.
+- The response schema **must** be the resource itself.
+  - The response **should** include the fully-populated resource, and **must**
+    include any fields that were sent and included in the update mask unless
+    they are input only (see AEP-203).
+  - If the update RPC is [long-running](#long-running-update), the response
+    **must** be an `Operation` for which the return type is the resource
+    itself.
+- The method **should** support partial resource update, and the HTTP verb
+  **should** be `PATCH`.
+
+{% tab proto %}
+
+```proto
+rpc UpdateBook(UpdateBookRequest) returns (Book) {
+  option (google.api.http) = {
+    patch: "/v1/{book.path=publishers/*/books/*}"
+    body: "book"
+  };
+  option (google.api.method_signature) = "book,update_mask";
+}
+```
+
+- The resource's `path` field **should** map to the URI path.
+  - The `{resource}.path` field **should** be the only variable in the URI
+    path.
+- There **must** be a `body` key in the `google.api.http` annotation, and it
+  **must** map to the resource field in the request message.
+  - All remaining fields **should** map to URI query parameters.
+- There **should** be exactly one `google.api.method_signature` annotation,
+  with a value of `"{resource},update_mask"`.
+
+**Note:** Unlike the other four standard methods, the URI path here references
+a nested field (`book.path`) in the example. If the resource field has a word
+separator, `snake_case` is used.
+
+{% tab oas %}
+
+**Note:** OAS example not yet written.
+
+{% endtabs %}
+
+### Request schema
+
+Update methods implement a common request pattern:
+
+- The request **must** contain a field for the resource.
+  - The name of this field **must** be the singular form of the resource's
+    name.
+- The request **must not** contain any required fields other than those
+  described in this section, and **should not** contain other optional fields
+  except those described in this or another AEP.
+
+{% tab proto %}
+
+```proto
+message UpdateBookRequest {
+  // The book to update.
+  //
+  // The book's `path` field is used to identify the book to update.
+  // Format: publishers/{publisher}/books/{book}
+  Book book = 1 [(google.api.field_behavior) = REQUIRED];
+
+  // The list of fields to update.
+  google.protobuf.FieldMask update_mask = 2;
+}
+```
+
+- The request message field for the resource **must** map to the `PATCH` body.
+- The request message field for the resource **should** be [annotated as
+  required][aep-203].
+  - The field **must** identify the [resource type][aep-123] of the resource
+    being updated.
+- If partial resource update is supported, a field mask **must** be included.
+  It **must** be of type `google.protobuf.FieldMask`, and it **must** be called
+  `update_mask`.
+  - The fields used in the field mask correspond to the resource being updated
+    (not the request message).
+  - The field **may** be required or optional. If it is required, it **must**
+    include the corresponding annotation. If optional, the service **must**
+    treat an omitted field mask as an implied field mask equivalent to all
+    fields that are populated (have a non-empty value).
+  - Update masks **must** support a special value `*`, meaning full replacement
+    (the equivalent of `PUT`).
+
+{% tab oas %}
+
+**Note:** OAS example not yet written.
+
+{% endtabs %}
+
+### Side effects
+
+In general, update methods are intended to update the data within the resource.
+Update methods **should not** trigger other side effects. Instead, side effects
+**should** be triggered by custom methods.
+
+In particular, this entails that [state fields][] **must not** be directly
+writable in update methods.
+
+### PATCH and PUT
+
+**TL;DR:** AEP-compliant APIs generally use the `PATCH` HTTP verb only, and do
+not support `PUT` requests.
+
+We standardize on `PATCH` because many organizations update stable APIs in
+place with backwards-compatible improvements. It is often necessary to add a
+new field to an existing resource, but this becomes a breaking change when
+using `PUT`.
+
+To illustrate this, consider a `PUT` request to a `Book` resource:
+
+    PUT /v1/publishers/123/books/456
+
+    {"title": "Mary Poppins", "author": "P.L. Travers"}
+
+Next consider that the resource is later augmented with a new field (here we
+add `rating`, and use a protobuf example without loss of generality):
+
+```proto
+message Book {
+  string title = 1;
+  string author = 2;
+
+  // Subsequently added to v1 in place...
+  int32 rating = 3;
+}
+```
+
+If a rating were set on a book and the existing `PUT` request were executed, it
+would wipe out the book's rating. In essence, a `PUT` request unintentionally
+would wipe out data because the previous version did not know about it.
+
+### Long-running update
+
+Some resources take longer to update a resource than is reasonable for a
+regular API request. In this situation, the API **should** use a long-running
+operation (AIP-151) instead:
+
+- The response type **must** be set to the resource (what the return type would
+  be if the method were not long-running).
+
+{% tab proto %}
+
+```proto
+rpc UpdateBook(UpdateBookRequest) returns (aep.api.Operation) {
+  option (google.api.http) = {
+    patch: "/v1/{book.name=publishers/*/books/*}"
+  };
+  option (aep.api.operation_info) = {
+    response_type: "Book"
+    metadata_type: "OperationMetadata"
+  };
+}
+```
+
+- Both the `response_type` and `metadata_type` fields **must** be specified.
+
+{% tab oas %}
+
+**Note:** OAS example not yet written.
+
+{% endtabs %}
+
+### Create or update
+
+If the service uses client-assigned resource paths, `Update` methods **may**
+expose a `bool allow_missing` field, which will cause the method to succeed in
+the event that the user attempts to update a resource that is not present (and
+will create the resource in the process):
+
+{% tab proto %}
+
+```proto
+message UpdateBookRequest {
+  // The book to update.
+  //
+  // The book's `path` field is used to identify the book to be updated.
+  // Format: publishers/{publisher}/books/{book}
+  Book book = 1 [(google.api.field_behavior) = REQUIRED];
+
+  // The list of fields to be updated.
+  google.protobuf.FieldMask update_mask = 2;
+
+  // If set to true, and the book is not found, a new book will be created.
+  // In this situation, `update_mask` is ignored.
+  bool allow_missing = 3;
+}
+```
+
+{% tab oas %}
+
+**Note:** OAS example not yet written.
+
+{% endtabs %}
+
+More specifically, the `allow_missing` flag triggers the following behavior:
+
+- If the method call is on a resource that does not exist, the resource is
+  created. All fields are applied regardless of any provided field mask.
+  - However, if any required fields are missing or fields have invalid values,
+    an `INVALID_ARGUMENT` error is returned.
+- If the method call is on a resource that already exists, and all fields
+  match, the existing resource is returned unchanged.
+- If the method call is on a resource that already exists, only fields declared
+  in the field mask are updated.
+
+The user **must** have the update permissions to call `Update` even with
+`allow_missing` set to `true`.
+
+### Etags
+
+An API may sometimes need to allow users to send update requests which are
+guaranteed to be made against the most current data (a common use case for this
+is to detect and avoid race conditions). Resources which need to enable this do
+so by including a `string etag` field, which contains an opaque,
+server-computed value representing the content of the resource.
+
+In this situation, the resource **should** contain a `string etag` field:
+
+{% tab proto %}
+
+```proto
+message Book {
+  option (google.api.resource) = {
+    type: "library.example.com/Book"
+    pattern: "publishers/{publisher}/books/{book}"
+  };
+
+  // The resource path of the book.
+  // Format: publishers/{publisher}/books/{book}
+  string path = 1 [(google.api.field_behavior) = IDENTIFIER];
+
+  // The title of the book.
+  // Example: "Mary Poppins"
+  string title = 2;
+
+  // The author of the book.
+  // Example: "P.L. Travers"
+  string author = 3;
+
+  // The etag for this book.
+  // If this is provided on update, it must match the server's etag.
+  string etag = 4;
+}
+```
+
+{% tab oas %}
+
+**Note:** OAS example not yet written.
+
+{% endtabs %}
+
+The `etag` field **may** be either [required][] or [optional][]. If it is set,
+then the request **must** succeed if and only if the provided etag matches the
+server-computed value, and **must** fail with an `ABORTED` error otherwise. The
+`update_mask` field in the request does not affect the behavior of the `etag`
+field, as it is not a field _being_ updated.
+
+### Expensive fields
+
+APIs sometimes encounter situations where some fields on a resource are
+expensive or impossible to reliably return.
+
+This can happen in a few situations:
+
+- A resource may have some fields that are very expensive to compute, and that
+  are generally not useful to the customer on update requests.
+- A single resource sometimes represents an amalgamation of data from multiple
+  underlying (and eventually consistent) data sources. In these situations, it
+  may be infeasible to return authoritative information on the fields that were
+  not changed.
+
+In this situation, an API **may** return back only the fields that were updated
+and omit the rest. APIs that do this **must** document this behavior.
+
+### Errors
+
+See [errors][], in particular [when to use PERMISSION_DENIED and NOT_FOUND
+errors][permission-denied].
+
+In addition, if the user does have proper permission, but the requested
+resource does not exist, the service **must** error with `NOT_FOUND` (HTTP 404)
+unless `allow_missing` is set to `true`.
+
+<!-- prettier-ignore-start -->
+[aep-121]: ./0121.md
+[aep-128]: ./0128.md
+[aep-203]: ./0203.md
+[create]: ./0133.md
+[errors]: ./0193.md
+[management plane]: ./0111.md#management-plane
+[permission-denied]: ./0193.md#permission-denied
+[state fields]: ./0216.md
+[strong consistency]: ./0121.md#strong-consistency
+[required]: ./0203.md#required
+[optional]: ./0203.md#optional
+<!-- prettier-ignore-end -->

aep/general/0134/aep.md.j2

@@ -1,6 +1,6 @@
 ---
 id: 134
-state: reviewing
+state: approved
 slug: update
 created: 2023-01-22
 placement: