An expiration date is the point after which an API resource is intended to be deleted or no longer retained. It makes retention behavior explicit and predictable. section 10.3.9 section 25.3.5
Choose a simple policy that matches the resource and make its edge cases explicit:
- Keep resources forever when storage is manageable; otherwise use a rolling window based on completion time rather than creation time. section 10.3.9
- Prefer one clear expiration rule over chains such as archive-then-delete, which complicate purging and confuse consumers. section 10.3.9
- Apply consistent lifetimes across related operation result types so resources do not disappear unpredictably. section 10.3.9
- Set expireTime when a resource becomes soft-deleted, clear it when the resource is undeleted, and permanently remove it once the deadline is reached. section 25.3.5
- Document page-token lifetimes; short periods are usually sufficient because an expired token can be retried, while cache retention can begin around five minutes with access-based renewal. section 21.3.2 section 26.3.5
Soft-deleting a chat room
A deleted ChatRoom receives an expireTime calculated from the current policy, such as 30 days. If it is undeleted, expireTime becomes null. A cleanup process removes resources whose deleted flag is true and whose expiration time has arrived. section 25.3.5
Listing 10.16 Adding an expiration field to the Operation interface
interface Operation<ResultT, MetadataT> {
id: string;
done: boolean;
expireTime: Date; #1
result?: ResultT | OperationError;
metadata?: MetadataT;
}
Shows expireTime as a first-class field on an Operation resource. section 10.3.9
Listing 25.8 Adding a new expiration time field to a resource
interface ChatRoom {
id: string;
// ...
deleted: boolean;
expireTime: Date; #1
}
Shows expireTime alongside the deleted flag on a soft-deletable resource. section 25.3.5
Treat the duration as a policy, not an immutable implementation detail: changing it should normally affect newly soft-deleted resources, while existing deadlines remain stable. Check regulatory requirements before enabling permanent expiration. section 25.3.5 section 25.4
