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.

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
Show file tree
Hide file tree
Changes from 2 commits
Commits
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
44 changes: 44 additions & 0 deletions aip/general/0214/aip.md.j2
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# 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. 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,
Copy link

Choose a reason for hiding this comment

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

"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).

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

Choose a reason for hiding this comment

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

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.


For some resources, a relative time offset may be more appropriate than a date.
Copy link

Choose a reason for hiding this comment

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

I'd use "instant in time" rather than "date" here, to avoid any ambiguity.

Copy link

Choose a reason for hiding this comment

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

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

Choose a reason for hiding this comment

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

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?


## 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).
7 changes: 7 additions & 0 deletions aip/general/0214/aip.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
id: 214
state: approved
created: 2018-06-19
placement:
category: design-patterns
order: 120
26 changes: 26 additions & 0 deletions aip/general/0214/expiry.oas.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
---
openapi: 3.0.3
info:
title: Library
version: 1.0.0
components:
schema:
Book:
description: This book will self-destruct.
properties:
name:
type: string
description: |
The name of the book.
Format: publishers/{publisher}/books/{book}
expire_time:
type: string
format: date-time
description: |
Timestamp in UTC of when this resource is considered expired.
This is *always* provided on output, regardless of what was sent
on input.
ttl_seconds:
type: integer
description: The TTL for this resource.
writeOnly: true
42 changes: 42 additions & 0 deletions aip/general/0214/expiry.proto
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
// Copyright 2021 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/timestamp.proto";

// This book will self-destruct.
message Book {
option (google.api.resource) = {
type: "library.googleapis.com/Book"
pattern: "publishers/{publisher}/books/{book}"
};

// The name of the resource; the format is: ...
string name = 1;

oneof expiration {
// 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.Timestamp expire_time = 2;

// Input only. The TTL for this resource.
google.protobuf.Duration ttl = 3
[(google.api.field_behavior) = INPUT_ONLY];
}
}