Port 0214 from aip

aep/general/0214/aep.md.j2

@@ -1,5 +1,74 @@
 # Resource expiration
 
-**Note:** This AEP has not yet been adopted. See
-[this GitHub issue](https://github.com/aep-dev/aep.dev/issues/19) for more
-information.
+Customers often want to provide the time that a given resource or resource
+attribute is no longer useful or valid (e.g. a rotating security key). Currently
+we recommend that customers do this by specifying an exact "expiration time"
+into a `Timestamp expire_time` field; however, this adds
+additional strain on the user when they want to specify a relative time offset
+until expiration rather than a specific time until expiration.
+
+Furthermore, the world understands the concept of a "time-to-live", often
+abbreviated to TTL, but the typical format of this field (an integer, measured
+in seconds) results in a sub-par experience when using an auto-generated client
+library.
+
+## Guidance
+
+1.  APIs wishing to convey an expiration **must** rely on a
+    `Timestamp` field called `expire_time`.
+2.  APIs wishing to allow a relative expiration time must define a `oneof`
+    called `expiration` (or `{something}_expiration`) containing both the
+    `expire_time` field and a separate `Duration`
+    field called `ttl`, the latter marked as input only.
+3.  APIs **must** always return the expiration time in the `expire_time` field
+    and leave the `ttl` field blank when retrieving the resource.
+4.  APIs that rely on the specific semantics of a "time to live" (e.g., DNS
+    which must represent the TTL as an integer) **may** use an `int64 ttl`
+    field (and **should** provide an [aep.dev/not-precedent](./0200.md) comment
+    in this case).
+
+### Example
+
+{% tab proto %}
+```proto
+message ExpiringResource {
+  // google.api.resource and other annotations and fields
+
+  oneof expiration {
+    // Timestamp in UTC of when this resource is considered expired.
+    // This is *always* provided on output, regardless of what was sent
+    // on input.
+    google.protobuf.Timestamp expire_time = 2;
+
+    // Input only. The TTL for this resource.
+    google.protobuf.Duration ttl = 3 [(google.api.field_behavior) = INPUT_ONLY];
+  }
+}
+```
+{% tab oas %}
+**Note:**  OAS content not yet written.
+
+{% endtabs %}
+
+## Rationale
+
+### Alternatives considered
+
+#### A new standard field called `ttl`
+
+We considered allowing a standard field called `ttl` as an alternative way of
+defining the expiration, however doing so would require that API services
+continually update the field, like a clock counting down. This could
+potentially cause problems with the read-modify-write lifecycle where a
+resource is being processed for some time, and effectively has its life
+extended as a result of that processing time.
+
+#### Always use `expire_time`
+
+This is the current state of the world with a few exceptions. In this scenario,
+we could potentially push the computation of `now + ttl = expire_time` into
+client libraries; however, this leads to a somewhat frustrating experience in
+the command-line and using REST/JSON. Leaving things as they are is typically
+the default, but it seems many customers want the ability to define relative
+expiration times as it is quite a bit easier and removes questions of time
+zones, stale clocks, and other silly mistakes.

aep/general/0214/aep.yaml

@@ -2,6 +2,6 @@
 id: 214
 state: reviewing
 slug: resource-expiration
-created: 2023-01-22
+created: 2024-03-14
 placement:
   category: design-patterns