|
1 | 1 | # Resource expiration |
2 | 2 |
|
3 | | -**Note:** This AEP has not yet been adopted. See |
4 | | -[this GitHub issue](https://github.com/aep-dev/aep.dev/issues/19) for more |
5 | | -information. |
| 3 | +Customers often want to provide the time that a given resource or resource |
| 4 | +attribute is no longer useful or valid (e.g. a rotating security key). Currently |
| 5 | +we recommend that customers do this by specifying an exact "expiration time" |
| 6 | +into a `Timestamp expire_time` field; however, this adds |
| 7 | +additional strain on the user when they want to specify a relative time offset |
| 8 | +until expiration rather than a specific time until expiration. |
| 9 | + |
| 10 | +Furthermore, the world understands the concept of a "time-to-live", often |
| 11 | +abbreviated to TTL, but the typical format of this field (an integer, measured |
| 12 | +in seconds) results in a sub-par experience when using an auto-generated client |
| 13 | +library. |
| 14 | + |
| 15 | +## Guidance |
| 16 | + |
| 17 | +1. APIs wishing to convey an expiration **must** rely on a |
| 18 | + `Timestamp` field called `expire_time`. |
| 19 | +2. APIs wishing to allow a relative expiration time must define a `oneof` |
| 20 | + called `expiration` (or `{something}_expiration`) containing both the |
| 21 | + `expire_time` field and a separate `Duration` |
| 22 | + field called `ttl`, the latter marked as input only. |
| 23 | +3. APIs **must** always return the expiration time in the `expire_time` field |
| 24 | + and leave the `ttl` field blank when retrieving the resource. |
| 25 | +4. APIs that rely on the specific semantics of a "time to live" (e.g., DNS |
| 26 | + which must represent the TTL as an integer) **may** use an `int64 ttl` |
| 27 | + field (and **should** provide an [aep.dev/not-precedent](./0200.md) comment |
| 28 | + in this case). |
| 29 | + |
| 30 | +### Example |
| 31 | + |
| 32 | +{% tab proto %} |
| 33 | +```proto |
| 34 | +message ExpiringResource { |
| 35 | + // google.api.resource and other annotations and fields |
| 36 | + |
| 37 | + oneof expiration { |
| 38 | + // Timestamp in UTC of when this resource is considered expired. |
| 39 | + // This is *always* provided on output, regardless of what was sent |
| 40 | + // on input. |
| 41 | + google.protobuf.Timestamp expire_time = 2; |
| 42 | + |
| 43 | + // Input only. The TTL for this resource. |
| 44 | + google.protobuf.Duration ttl = 3 [(google.api.field_behavior) = INPUT_ONLY]; |
| 45 | + } |
| 46 | +} |
| 47 | +``` |
| 48 | +{% tab oas %} |
| 49 | +**Note:** OAS content not yet written. |
| 50 | + |
| 51 | +{% endtabs %} |
| 52 | + |
| 53 | +## Rationale |
| 54 | + |
| 55 | +### Alternatives considered |
| 56 | + |
| 57 | +#### A new standard field called `ttl` |
| 58 | + |
| 59 | +We considered allowing a standard field called `ttl` as an alternative way of |
| 60 | +defining the expiration, however doing so would require that API services |
| 61 | +continually update the field, like a clock counting down. This could |
| 62 | +potentially cause problems with the read-modify-write lifecycle where a |
| 63 | +resource is being processed for some time, and effectively has its life |
| 64 | +extended as a result of that processing time. |
| 65 | + |
| 66 | +#### Always use `expire_time` |
| 67 | + |
| 68 | +This is the current state of the world with a few exceptions. In this scenario, |
| 69 | +we could potentially push the computation of `now + ttl = expire_time` into |
| 70 | +client libraries; however, this leads to a somewhat frustrating experience in |
| 71 | +the command-line and using REST/JSON. Leaving things as they are is typically |
| 72 | +the default, but it seems many customers want the ability to define relative |
| 73 | +expiration times as it is quite a bit easier and removes questions of time |
| 74 | +zones, stale clocks, and other silly mistakes. |
0 commit comments