aip.md.j2

# Resource expiration

Sometimes it is necessary for a resource to have a defined lifespan. At the end 
of this lifespan, the resource expires but may still be accessible from the 
server. The duration or end of this lifespan may be controled by an API client, 
or determined by the server at the time of creation. Lifespans can be defined 
as an absolute time value or as a relative time offset. An absolute time value 
stored in the `expire_time` field is preferred. 

The `expire_time` of a resource is not intended to be a replacement for the `Cache-Control` header used to communicate client-side or CDN caching 
recommendations. The lifespan of a resource refers to the time it spends in a 
valid or actionable state, such as how long a certificate is valid, or how long 
an auction is active.

For some resources, a relative time offset may be more appropriate than an 
absolute time value. Furthermore, the world understands the concept of a 
"time-to-live", often abbreviated to TTL. However, the typical format of this 
field (an integer, measured in seconds) results in a sub-par experience when 
using an auto-generated client library. Nonetheless, a `ttl` field may be used 
in conjunction with the `expire_time` field.

## Guidance

Services wishing to convey an expiration **must** rely on a timestamp field
called `expire_time`. Services 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][aip-142]
field called `ttl`, the latter marked as input only:

{% tab proto %}

{% sample 'expiry.proto', 'message Book' %}

{% tab oas %}

{% sample 'expiry.oas.yaml', 'schema' %}

{% endtabs %}

Services **must** always return the expiration time in the `expire_time` field
and leave the `ttl` field blank when retrieving the resource.

Services 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 [aip.dev/not-precedent][aip-200] comment in this
case).