feat(AIP-121): adding guidance around consistency (#1060)

Google clients have implicit requirements around the
consistency today, but it is not explicitly stated in the AIPs.

Clarifying the guidance around consistency requirements.

Author: toumorokoshi

aip/general/0121.md

@@ -94,6 +94,38 @@ the standard methods. Custom methods offer the same design freedom as
 traditional RPC APIs, which can be used to implement common programming
 patterns, such as database transactions, import and export, or data analysis.
 
+### Strong Consistency
+
+For methods that operate on the [management plane][], the completion of those
+operations (either successful or with an error, LRO or synchronous) **must**
+mean that the state of the resource's existence and all user-settable values
+have reached a steady-state.
+
+[output only][] values unrelated to the resource [state][] **should** also have
+reached a steady-state. for values that are related to the resource [state][].
+
+Examples include:
+
+- Following a successful create that is is latest mutation on a resource, a get
+  request for a resource **must** return the resource.
+- Following a successful update that is the latest mutation on a resource, a get
+  request for a resource **must** return the final values from the update
+  request.
+- Following a successful delete that is the latest mutation on a resource, a get
+  request for a resource **must** return `NOT_FOUND` (or the resource with the
+  `DELETED` state value in the case of [soft delete][])
+
+Clients of resource-oriented APIs often need to orchestrate multiple operations
+in sequence (e.g. create resource A, create resource B which depends on A), and
+ensuring that resources immediately reflect steady user state after an operation
+is complete ensures clients can rely on method completion as a signal to begin
+the next operation.
+
+[output only][] fields ideally would follow the same guidelines, but as
+these fields can often represent a resources live state, it's sometimes
+necessary for these values to change after a successful mutation operation to
+reflect a state change.
+
 ### Stateless protocol
 
 As with most public APIs available today, resource-oriented APIs **must**
@@ -129,23 +161,27 @@ This requirement does not apply to relationships that are expressed via
 [output only][] fields, as they do not require the user to specify the values
 and in turn do not increase resource management complexity.
 
-[rest]: https://en.wikipedia.org/wiki/Representational_state_transfer
-[rpc]: https://en.wikipedia.org/wiki/Remote_procedure_call
-[stateless protocol]: https://en.wikipedia.org/wiki/Stateless_protocol
-[get]: ./0131.md
-[list]: ./0132.md
 [create]: ./0133.md
-[update]: ./0134.md
-[delete]: ./0135.md
 [custom methods]: ./0136.md
+[delete]: ./0135.md
 [directed acyclic graph]: https://en.wikipedia.org/wiki/Directed_acyclic_graph
-[resource references]: ./0122.md#fields-representing-another-resource
+[get]: ./0131.md
+[list]: ./0132.md
+[management plane]: ./0111.md#management-plane
 [output only]: ./0203.md#output-only
+[rest]: https://en.wikipedia.org/wiki/Representational_state_transfer
+[resource references]: ./0122.md#fields-representing-another-resource
+[rpc]: https://en.wikipedia.org/wiki/Remote_procedure_call
 [singleton resources]: ./0156.md
+[soft delete]: ./0164.md
+[state]: ./0216.md
+[stateless protocol]: https://en.wikipedia.org/wiki/Stateless_protocol
+[update]: ./0134.md
 
 
 ## Changelog
 
+- **2023-08-24**: Added guidance on consistency guarantees of methods.
 - **2023-07-23**: Clarify stateless protocol definition.
 - **2023-01-21**: Explicitly require matching schema across standard methods.
 - **2022-12-19**: Added a section requiring Get and List.

aip/general/0133.md

@@ -60,6 +60,10 @@ rpc CreateBook(CreateBookRequest) returns (Book) {
 - There **should** be exactly one `google.api.method_signature` annotation,
   with a value of `"parent,{resource},{resource}_id"`, or "`"parent,{resource}"`
   if the resource ID is not required.
+- If the API is operating on the [management plane][], the operation should have
+  [strong consistency][]: the completion of a create operation **must** mean
+  that all user-settable values and the existence of the resource have reached a
+  steady-state and reading resource state returns a consistent response.
 
 ### Request message
 
@@ -128,9 +132,9 @@ to done if the request is effectively immediate.
 
 An API **must** allow a user to specify the ID component of a resource (the last
 segment of the resource name) on creation if the API is operating on the
-[Management Plane][].
+[management plane][].
 
-On the [Data Plane][], an API **should** allow a user to specify the ID.
+On the [data plane][], an API **should** allow a user to specify the ID.
 Exceptional cases should have the following behavior:
 
 - The data plane resource allows identical records without a need to
@@ -203,15 +207,17 @@ name and use it in references from other resources.
 [aip-155]: ./0155.md
 [aip-203]: ./0203.md
 [aip-210]: ./0210.md
-[Data Plane]: ./0111.md#data-plane
-[Management Plane]: ./0111.md#management-plane
+[data plane]: ./0111.md#data-plane
+[management plane]: ./0111.md#management-plane
 [errors]: ./0193.md
 [field_behavior]: ./203.md
 [Declarative clients]: ./0009.md#declarative-clients
 [permission-denied]: ./0193.md#permission-denied
+[strongly consistent]: ./0121.md#strong-consistency
 
 ## Changelog
 
+- **2023-08-24**: Adding consistency requirement.
 - **2023-05-11**: Changing guidance around resource_id to a must.
 - **2022-11-04**: Referencing aggregated error guidance in AIP-193, similar to
   other CRUDL AIPs.

aip/general/0134.md

@@ -58,8 +58,14 @@ rpc UpdateBook(UpdateBookRequest) returns (Book) {
 - 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"`.
+- There **should** be exactly one `google.api.method_signature` annotation, with
+  a value of `"{resource},update_mask"`.
+- If the API is operating on the [management plane][], the operation should have
+  [strong consistency][]: the completion of an update operation **must** mean
+  that all user-settable values and the existence of the resource have reached a
+  steady-state and reading resource state returns a consistent response.
+
+
 
 **Note:** Unlike the other four standard methods, the URI path here references
 a nested field (`book.name`) in the example. If the resource field has a word
@@ -277,13 +283,16 @@ does not exist, the service **must** error with `NOT_FOUND` (HTTP 404) unless
 [aip-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
 
 ## Changelog
 
+- **2023-08-26**: Adding consistency requirement.
 - **2023-07-17**: Make `update_mask` name guidance a **must**.
 - **2022-11-04**: Aggregated error guidance to AIP-193.
 - **2022-06-02**: Changed suffix descriptions to eliminate superfluous "-".

aip/general/0135.md

@@ -53,6 +53,12 @@ rpc DeleteBook(DeleteBookRequest) returns (google.protobuf.Empty) {
 - There **should** be exactly one `google.api.method_signature` annotation,
   with a value of `"name"`. If an etag or force field are used, they **may** be
   included in the signature.
+- If the API is operating on the [Management Plane][], the operation should have
+  [strong consistency][]: the completion of a delete operation **must** mean
+  that the existence of the resource has reached a steady-state and reading
+  resource state returns a consistent response.
+
+
 
 The Delete method **should** succeed if and only if a resource was present and
 was successfully deleted. If the resource did not exist, the method **should**
@@ -222,6 +228,8 @@ exist, the service **must** error with `NOT_FOUND` (HTTP 404) unless
 [aip-203]: ./0203.md
 [aip-214]: ./0214.md
 [aip-216]: ./0216.md
+[management plane]: ./0111.md#management-plane
+[strong consistency]: ./0121.md#strong-consistency
 [etag]: ./0134.md#etags
 
 ## Further reading
@@ -231,6 +239,7 @@ exist, the service **must** error with `NOT_FOUND` (HTTP 404) unless
 
 ## Changelog
 
+- **2023-08-24**: Adding consistency requirement.
 - **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.