feat(AIP-121): adding guidance around consistency #1060
Conversation
Google clients have implicit requirements around the consistency today, but it is not explicitly stated in the AIPs. Clarifying the guidance around consistency requirements.
- normalizing wording to "strong consistency", to help clarify that this is referring to distributed system consistency. - clarifying LRO scope for operation completion.
|
@bgrant0607 I've ended up using the term "strong consistency" across the board, as you suggested. Agreed it's helpful to clarify. PTAL. |
adding caveat around management plane for strong consistency, to allow some data-plane use cases of standard methods like eventual consistency due to large volumes of calls.
|
@alin04 can you TAL? this is the consistency discussion: i've added the caveat around management plane vs data plane. |
aip/general/0121.md
Outdated
| mean that the state of the resource's existence and all user-settable values | ||
| have reached a steady-state. | ||
|
|
||
| [output only][] values **should** also have reached a steady-state, except |
There was a problem hiding this comment.
basically that output-only values should be stable if they aren't related to resource state. E.g. they're not jittering around in values. This is for the same reason the operation itself should be consistent: the user should expect resource creation marks some event where the resource is more or less stable, since declarative clients have trouble reconciling transient state, and users will be surprised if the resource is constantly changing.
Of course being related to resource state is a little vague, since the only definition of state we have is AIP-216.
There was a problem hiding this comment.
Like server generated IDs? create_time ?
There was a problem hiding this comment.
those are good examples of things that are steady state. AIP-216's state field is an example of what shouldn't be.
Would adding examples help? Or do you think this statement is too ambiguous?
aip/general/0121.md
Outdated
|
|
||
| Examples include: | ||
|
|
||
| - Following a successful create, a get request for a resource **must** |
There was a problem hiding this comment.
Unless there's a race condition whereby it got deleted immediately. Same below for update.
If two people are updating, (unless the service handles stale state), then last one will win.
There was a problem hiding this comment.
good call! I updated the working to state that it has to be the latest mutation on the resource (should clarify that last operation wins). WDYT?
aip/general/0121.md
Outdated
| mean that the state of the resource's existence and all user-settable values | ||
| have reached a steady-state. | ||
|
|
||
| [output only][] values **should** also have reached a steady-state, except |
There was a problem hiding this comment.
| [output only][] values **should** also have reached a steady-state, except | |
| [output only][] values unrelated to the resource [state][] **should** also have reached a steady-state. |
aip/general/0121.md
Outdated
| mean that the state of the resource's existence and all user-settable values | ||
| have reached a steady-state. | ||
|
|
||
| [output only][] values **should** also have reached a steady-state, except |
There was a problem hiding this comment.
Like server generated IDs? create_time ?
Google clients have implicit requirements around the consistency today, but it is not explicitly stated in the AIPs.
Clarifying the guidance around consistency requirements.