AIP-214: Adding clarification #44
Conversation
…rces that expire, and not about the TTL or expiration time of a cached message.
|
Oh, also, @lukesneeringer, I could not run this branch locally due to the .j2 file. A quick glance at a few other AIPs... is this the only AIP in this branch that is using jinja for the main file? I looked at the documentation, if you are aware of any quick answers, let me know. Otherwise, I can start digging into the generator if I need to. |
aip/general/0214/aip.md.j2
Outdated
| 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, |
There was a problem hiding this comment.
"Regardless of how the source of this time" doesn't sound right. I'm not sure whether it should be "Regardless of the source of this time" or "Regardless of how this time is determined" (or similar).
aip/general/0214/aip.md.j2
Outdated
| 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. |
There was a problem hiding this comment.
Nit-pick, but that sounds like "certificate" and "auction" are actionable states. How about:
The lifespan of a resource refers to the time it spends in a valid or actionable state, such as a
how long a certificate is valid, or how long an auction is open for bidding.
aip/general/0214/aip.md.j2
Outdated
| 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. |
There was a problem hiding this comment.
I'd use "instant in time" rather than "date" here, to avoid any ambiguity.
aip/general/0214/aip.md.j2
Outdated
| 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. |
There was a problem hiding this comment.
All good so far, but this paragraph doesn't quite feel like the end of the section. Is there an extra sentence we could use to close it?
aip/general/0214/aip.md.j2
Outdated
| 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. |
| 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 |
There was a problem hiding this comment.
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...
| 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. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
You didn't, I pushed the updates right before the meeting where we made that clarification.
@lukesneeringer, I would especially appreciate your review here, as I'm worried I might be stepping on toes.
I'm hoping the adjustments I made to the first paragraph will help clarify that this is about resource expiration. Moreso, I realized that we weren't just talking about communicating resource expiration, but also about setting it (i.e. If the client sets it, or even changes it).
Based on the other notes, I'm not sure if there is anything else that we should change in this AIP, as I thought we agreed (maybe I'm the only one who agreed, in my head) that the other discussions were edge cases that should be handled in an AIP extension. @jskeet You're thoughts on this topic would be appreciated as well.
Thanks!