Skip to content

Commit

Permalink
fix(AIP-164): clarify 164 is declarative-unfriendly (#1171)
Browse files Browse the repository at this point in the history
Internal feedback has proven that soft-deletable resources
are unfriendly to declarative clients. This was updated
in AIP-128 but not in AIP-164.

Fixes #1138
  • Loading branch information
toumorokoshi committed Jul 14, 2023
1 parent ff1ad3a commit 95a9860
Showing 1 changed file with 5 additions and 18 deletions.
23 changes: 5 additions & 18 deletions aip/general/0164.md
Original file line number Diff line number Diff line change
Expand Up @@ -112,24 +112,11 @@ the resources indefinitely. Regardless of what strategy is selected, the API

### Declarative-friendly resources

A resource that is declarative-friendly (AIP-128) **should** support soft
delete and undelete.

**Important:** There is an ambiguity in declarative tooling between "create"
and "undelete". When given an alias which was previously deleted and a
directive to make it exist, tooling usually does not know if the intent is to
restore the previously-deleted resource, or create a new one with the same
alias. Declarative tools **should** resolve this ambiguity in favor of creating
a new resource: the only way to undelete is to explicitly use the undelete RPC
(an imperative operation), and declarative tools **may** elect not to map
anything to undelete at all.

Declarative-friendly resources **must** use long-running operations for both
soft delete and undelete. The service **may** return an LRO that is already set
to done if the request is effectively immediate.

Declarative-friendly resources **must** include `validate_only` (AIP-163) and
`etag` (AIP-154) in their `Undelete` methods.
Soft-deletable resources have a poorer experience than hard-deleted resources in
declarative clients: since an ID on a soft-deleted resource is not re-usable
unless a custom method (undelete) is called, an imperative client must be
introduced or hand-written code is required to incorporate the usage of the
custom method.

### Errors

Expand Down

0 comments on commit 95a9860

Please sign in to comment.