• File Bug
• View source
• Edit this page

AIP-214

Resource expiration

Customers often want to provide the time that a given resource or resourceattribute is no longer useful or valid (e.g. a rotating security key). Currentlywe recommend that customers do this by specifying an exact "expiration time"into agoogle.protobuf.Timestamp expire_time field; however, this addsadditional strain on the user when they want to specify a relative time offsetuntil expiration rather than a specific time until expiration.

Furthermore, the world understands the concept of a "time-to-live", oftenabbreviated to TTL, but the typical format of this field (an integer, measuredin seconds) results in a sub-par experience when using an auto-generated clientlibrary.

Guidance

1. APIs wishing to convey an expirationmust rely on agoogle.protobuf.Timestamp field calledexpire_time.
2. APIs wishing to allow a relative expiration timemust define aoneof calledexpiration (or{something}_expiration) containing both theexpire_time field and a separategoogle.protobuf.Duration field calledttl, the latter marked as input only.
3. APIsmust always return the expiration time in theexpire_time field and leave thettl 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 anint64 ttl field (andshould provide anaip.dev/not-precedent comment in this case).

Example

messageExpiringResource{// google.api.resource and other annotations and fieldsoneofexpiration{// 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.Timestampexpire_time=2;// Input only. The TTL for this resource.google.protobuf.Durationttl=3[(google.api.field_behavior)=INPUT_ONLY];}}

Rationale

Alternatives considered

A new standard field calledttl

We considered allowing a standard field calledttl as an alternative way ofdefining the expiration, however doing so would require that API servicescontinually update the field, like a clock counting down. This couldpotentially cause problems with the read-modify-write lifecycle where aresource is being processed for some time, and effectively has its lifeextended as a result of that processing time.

Always useexpire_time

This is the current state of the world with a few exceptions. In this scenario,we could potentially push the computation ofnow + ttl = expire_time intoclient libraries; however, this leads to a somewhat frustrating experience inthe command-line and using REST/JSON. Leaving things as they are is typicallythe default, but it seems many customers want the ability to define relativeexpiration times as it is quite a bit easier and removes questions of timezones, stale clocks, and other silly mistakes.