feat: AIP-165 – Criteria-based delete

[lukesneeringer]

This adds a refactored AIP-165.

I really like some of the precedents set in #2; for example, mirroring the structure there required me to add a full section on errors that I consider to be quite useful. Similarly, separating the behavior from the IDL still works well.

There is an open question here about long-running operations, which I do not know how to properly handle in OAS and need to discuss with @mkistler.

[rhamiltonsf]

I agree with this AIP and can completely see the use case where this might need to exist, but question if this needs to be an AIP. If it does need to be an AIP, I question if it needs to be so prescriptive.

My immediate thoughts go to the Cloudfront API which has the concept of an invalidation in which you can define a URL with wildcards which will clear the CDN cache for all content that matches those URLs.

I like AWS's approach because it very clearly defines a resource that represents a long running job on the backend. Where I think this approach conflicts with this AIP is that this AIP is really just a customized custom method.

This AIP standardizes an approach that is inherently un-RESTful. The result will be that more people will lean on the option to create a purge API instead of innovating and creating something like a invalidation API.

[lukesneeringer]

I like AWS's approach because it very clearly defines a resource that represents a long running job on the backend. Where I think this approach conflicts with this AIP is that this AIP is really just a customized custom method.

I find this intriguing. We have been discussing this concept a lot internally (for other reasons).

Is an invalidation a single-point-in-time action? If I invalidate foo*, and then later I add foobar, does the presence of the invalidation from the past invalidate it ASAP? (From the documentation, it appears it is single-point-in-time.)

This also brings up a lot of questions around Google's current AIP-151, which we have been rehashing for declarative-friendly APIs internally, and possibly moving in the direction of something more like an invalidation.

[mkistler]

Looks good. 👍

IBM does not have any provision for this form of delete in our API Guidelines, but if we ever chose to add it this looks like a reasonable formulation to use.

We'll want to add the OpenAPI details in Interface Definitions at some point.