feat(164): specify create overwrites soft deleted (#371)

To help ensure that declarative clients do not have a degraded user experience with resources that implement soft-delete, specify that create overwrites an existing soft-deleted resource, or has a query parameter that allows a client to specify overwrite behavior.

This ensures that a declarative tool can still properly apply a resource, overwriting it instead of requiring an out of band force delete or having the user modify the ID of the resource.

fixes #111 (which includes some significant debate and context on why this approach was chosen).

Inlined description:

In #365, there was additional discussion or the viability of the pattern. @odsod brings up valid points that the cost to implement my proposed pattern is quite a bit different (requires two different collections), and perhaps implements a sort of "snapshot" resource collection than a soft-deleted resource, whose main intention is primarily around having a resource that exists until some expiry date rather than a snapshot that should be recovered.

In addition, most who have joined AEP live meetings have raised valid examples of soft deleted resources in their APIs (e.g. cryptographic keys in Azure), and therefore the omissions of this pattern might invalidate those resources.

As such, combined with the primary motivation here to eliminate the poor UX with declarative clients which may need to overwrite the resource, this change acts as a more surgical fix to ensure that a create behaves like any other resource (specifically allowing the recreation of one), even when using the soft delete pattern.

Author: toumorokoshi

Makefile

@@ -11,10 +11,10 @@ install:
 
 lint:
 	npm run lint
-	python scripts/fix.py --path ./aep/general/
-	python scripts/validate_links.py
+	python3 scripts/fix.py --path ./aep/general/
+	python3 scripts/validate_links.py
 
 check:
 	npm run check
-	python scripts/fix.py --check --path ./aep/general/
-	python scripts/validate_links.py
+	python3 scripts/fix.py --check --path ./aep/general/
+	python3 scripts/validate_links.py

aep/general/0121/aep.md.j2

@@ -106,8 +106,7 @@ Examples of strong consistency include:
   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][])
+  get request for a resource **must** return `NOT_FOUND`.
 
 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),

aep/general/0164/aep.md.j2

@@ -60,20 +60,26 @@ A resource that supports soft delete **should** provide an `Undelete` method:
 
 {% endtabs %}
 
-### Long-running undelete
+### Create
 
-Some resources take longer to undelete a resource than is reasonable for a
-regular API request. In this situation, the API **should** follow the
-long-running request pattern AEP-151.
+Create methods **must** adhere to one of the following:
+
+- If a user attempts a create on a soft-deleted resource, the create **must**
+  succeed, acting as if the resource did not exist previously.
+- The create **must** accept a field (query parameter for OAS),
+  `overwrite_soft_deleted`. If set to `false`, the request **must** fail if a
+  soft-deleted resource exists. If set to `true`, the request **must** succeed
+  if the resource exists acting as if the resource did not exist previously.
 
 ### List and Get
 
-Soft-deleted resources **should not** be returned in `List` AEP-132 responses
-by default (unless `bool show_deleted` is true).
+Soft-deleted resources **must not** be returned in `List` AEP-132 responses by
+default (unless `bool show_deleted` is true).
 
-A `Get` AEP-131 request for a soft deleted resource **should** error with
-`410 Gone` unless `bool show_deleted` is true, in which case soft-deleted
-resources **must** return the resource.
+A `Get` AEP-131 request for a soft deleted resource **must** return with a
+`404 Not Found` response unless `bool show_deleted` is true, in which case
+soft-deleted resources **must** return the resource (with the `DELETED` state
+value if the resource includes a [`state` field](/states)).
 
 Services that soft delete resources **may** choose a reasonable strategy for
 purging those resources, including automatic purging after a reasonable time
@@ -84,9 +90,6 @@ removed.
 
 ### Declarative-friendly resources
 
-A resource that is declarative-friendly AEP-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
@@ -96,27 +99,17 @@ 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` AEP-163 and
-`etag` AEP-154 in their `Undelete` methods.
-
 ### Errors
 
-If the user does not have permission to access the resource, regardless of
-whether or not it exists, the service **must** error with `403 Forbidden`.
-Permission **must** be checked prior to checking if the resource exists.
+Also see [errors](/errors) for additional guidance.
 
 If the user does have proper permission, but the requested resource does not
 exist (either it was never created or already expunged), the service **must**
 error with `404 Not Found`.
 
 If the user calling a soft `Delete` has proper permission, but the requested
 resource is already deleted, the service **must** succeed if `allow_missing` is
-`true`, and **should** error with `404 Not Found` if `allow_missing` is
-`false`.
+`true`, and **must** error with `404 Not Found` if `allow_missing` is `false`.
 
 If the user calling `Undelete` has proper permission, but the requested
 resource is not deleted, the service **must** error with `409 Conflict`.