Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

AIP-214: Adding clarification #44

Open
wants to merge 3 commits into
base: aip-214
Choose a base branch
from
Open

AIP-214: Adding clarification #44

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0dc7cfe
feat: AIP-214 – Resource expiration
Jul 12, 2021
ab39dab
updates to resource expiration to clarify that the AIP is about resou…
rhamiltonsf Nov 2, 2021
c253d70
re-writing guidance based on feedback. Making the introduction more r…
rhamiltonsf Nov 9, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 16 additions & 14 deletions aip/general/0214/aip.md.j2
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,20 +2,22 @@

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. This "expiration time" may be defined by a customer, or determined by
the server at the time of creation. Regardless of how the source of this time,
we recommend it is communicated via the `expire_time` property.

The `expire_time` of a resource is not meant to replace the `Cache-Control`
header to communicate client-side or CDN caching. The lifespan of a resource
refers to the time it spends in a valid or actionable state, such as a
certificate or an auction.

For some resources, a relative time offset may be more appropriate than a date.
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.
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
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would be nice to rewrap this paragraph just to avoid the one line sticking out. (I know it's not visible when rendered.) Once we've work out what everything should say, of course...

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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've now lost track of what we said in yesterday's meeting... I thought we were going to shift the examples to more of a soft-delete emphasis? I may well have misunderstood.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You didn't, I pushed the updates right before the meeting where we made that clarification.


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

Expand Down