-
Notifications
You must be signed in to change notification settings - Fork 3
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
base: aip-214
Are you sure you want to change the base?
Changes from 2 commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
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, | ||
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. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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:
|
||
|
||
For some resources, a relative time offset may be more appropriate than a date. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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). |
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 |
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 |
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]; | ||
} | ||
} |
There was a problem hiding this comment.
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).