Merge branch 'main' into aip-147

Author: Luke Sneeringer

aip/general/0126/aip.md.j2

@@ -0,0 +1,138 @@
+# Enumerations
+
+It is common for a field to only accept or provide a discrete and limited set
+of values. In these cases, it can be useful to use enumerations (generally
+abbreviated "enums") in order to clearly communicate what the set of allowed
+values are.
+
+## Guidance
+
+APIs **may** expose enum objects for sets of values that are expected to change
+infrequently:
+
+```typescript
+// Possible formats in which a book may be published.
+enum Format {
+  // The printed format, in hardback.
+  Hardback = 'HARDBACK',
+
+  // The printed format, in paperback.
+  Paperback = 'PAPERBACK',
+
+  // An electronic book format.
+  Ebook = 'EBOOK',
+
+  // An audio recording.
+  Audiobook = 'AUDIOBOOK',
+}
+```
+
+- All enum values **should** use a consistent case format across an
+  organization. In many cases, this is dictated by the IDL the organization
+  uses.
+- Enums **should** document whether the enum is frozen or they expect to add
+  values in the future.
+
+### When to use enums
+
+Enums can be more accessible and readable than strings or booleans in many
+cases, but they do add overhead when they change. Therefore, enums **should**
+receive new values infrequently. While the definition of "infrequently" may
+change based on individual use cases, a good rule of thumb is no more than once
+a year. For enums that change frequently, the API **should** use a string and
+document the format.
+
+**Note:** If an enumerated value needs to be shared across APIs, an enum
+**may** be used, but the assignment between enum values and their wire
+representation **must** match.
+
+### Alternatives
+
+Enums **should not** be used when there is a competing, widely-adopted standard
+representation (such as with [language codes][bcp-47] or [media types][]).
+Instead, that standard representation **should** be used. This is true even if
+only a small subset of values are permitted, because using enums in this
+situation often leads to frustrating lookup tables when trying to use multiple
+APIs together.
+
+For enumerated values where the set of allowed values changes frequently, APIs
+**should** use a `string` field instead, and **must** document the allowed
+values. String fields with enumerated values **should** use a uniform case
+system (`snake_case`, `kebab-case`, etc.) throughout an organization.
+
+Boolean fields **may** be used in situations where it is clear that no further
+flexibility will be needed. The default value **must** be `false`.
+
+### Compatibility
+
+Adding values to an enum has the potential to be disruptive to existing
+clients. Consider code written against the `Format` enum in an earlier version
+where only the first two options were available:
+
+```typescript
+switch (book.format) {
+  case Format.Hardback:
+    // Do something...
+    break;
+  case Format.Paperback:
+    // Do something...
+    break;
+  default:
+    // When new enum values are introduced, pre-existing client code may
+    // throw errors or act in unexpected ways.
+    throw new Error('Unrecognized value.');
+}
+```
+
+Services **may** add new values to existing enums; however, they **should** add
+enums carefully; think about what will happen if a client system does not know
+about a new value.
+
+Additionally, in IDLs where enum values are presented in a specific order,
+services **should** only add new values to the end. An exception to this rule
+is if the enum conforms to an external standard (for example, an enum
+representing HTTP status codes would add a new 3xx value alongside the others,
+not at the end).
+
+## Interface Definitions
+
+{% tab proto %}
+
+{% sample 'enum.proto', 'enum Format' %}
+
+- The zero value of the enum **should** be the name of the enum itself followed
+  by the suffix `_UNSPECIFIED`. The service **may** either allow or prohibit
+  use of this value.
+- Enums which will only be used in a single message **should** be nested within
+  that message. In this case, the enum **should** be declared immediately
+  before it is used.
+- If multiple enums are in the same namespace, they **must not** share any
+  values. (This is because enums do not provide their own namespace for their
+  values in some languages.)
+- If an enumerated value needs to be shared across APIs, an enum **may** be
+  used, but the assignment between the value names and the tag numbers **must**
+  match.
+
+**Note:** When using protocol buffers, it is impossible to distinguish between
+`false` and unset. If this is a requirement, an enum **may** be a better design
+choice (although `google.protobuf.BoolValue` is also available).
+
+{% tab oas %}
+
+{% sample 'enum.oas.yaml', 'format' %}
+
+- Enumerated fields **should** be strings.
+- If the enum is optional, The `null` value **should** be used as the empty
+  value, and **should** be the first value specified.
+
+**Note:** If `null` is a valid value, OpenAPI 3.0 also requires that
+`nullable: true` is specified for the field.
+
+{% endtabs %}
+
+## Further reading
+
+- For states, a special type of enum, see AIP-216.
+
+[bcp-47]: https://en.wikipedia.org/wiki/IETF_language_tag
+[media types]: https://en.wikipedia.org/wiki/Media_type

aip/general/0126/aip.yaml

@@ -0,0 +1,7 @@
+---
+id: 126
+state: approved
+created: 2019-07-24
+placement:
+  category: resource-design
+  order: 60

aip/general/0126/enum.oas.yaml

@@ -0,0 +1,40 @@
+---
+openapi: 3.0.3
+info:
+  title: Library
+  version: 1.0.0
+components:
+  schema:
+    Book:
+      description: A representation of a single book.
+      properties:
+        name:
+          type: string
+          description: |
+            The name of the book.
+            Format: publishers/{publisher}/books/{book}
+        isbn:
+          type: string
+          description: |
+            The ISBN (International Standard Book Number) for this book.
+        title:
+          type: string
+          description: The title of the book.
+        authors:
+          type: array
+          items:
+            type: string
+          description: The author or authors of the book.
+        rating:
+          type: float
+          description: The rating assigned to the book.
+        format:
+          type: string
+          description: The format of the book.
+          nullable: true
+          enum:
+            - null
+            - HARDCOVER
+            - PAPERBACK
+            - EBOOK
+            - AUDIOBOOK

aip/general/0126/enum.proto

@@ -0,0 +1,62 @@
+// Copyright 2020 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/resource.proto";
+
+// A representation of a book.
+message Book {
+  option (google.api.resource) = {
+    type: "library.googleapis.com/Book"
+    pattern: "publishers/{publisher}/books/{book}"
+  };
+
+  // The name of the book.
+  // Format: publishers/{publisher}/books/{book}
+  string name = 1;
+
+  // The ISBN (International Standard Book Number) for this book.
+  string isbn = 2;
+
+  // The title of the book.
+  string title = 3;
+
+  // The author or authors of the book.
+  repeated string authors = 4;
+
+  // The rating assigned to the book.
+  float rating = 5;
+
+  // Possible formats in which the book may be published.
+  enum Format {
+    // Default value. This value is unused.
+    FORMAT_UNSPECIFIED = 0;
+
+    // The printed format, in hardback.
+    HARDBACK = 1;
+
+    // The printed format, in paperback.
+    PAPERBACK = 2;
+
+    // An electronic book format.
+    EBOOK = 3;
+
+    // An audio recording.
+    AUDIOBOOK = 4;
+  }
+
+  // The format of the book.
+  Format format = 6;
+}

aip/general/0154/aip.md

@@ -0,0 +1,105 @@
+# Resource freshness validation
+
+APIs often need to validate that a client and server agree on the current state
+of a resource before taking some kind of action on that resource. For example,
+two processes updating the same resource in parallel could create a race
+condition, where the latter process "stomps over" the effort of the former one.
+
+ETags provide a way to deal with this, by allowing the server to send a
+checksum based on the current content of a resource; when the client sends that
+checksum back, the server can ensure that the checksums match before acting on
+the request.
+
+## Guidance
+
+A resource **may** provide an `ETag` header when retrieving a single resource
+when it is important to ensure that the client has an up to date resource
+before acting on certain requests:
+
+```
+200 OK
+Content-type: application/json
+ETag: "55cc0347-66fc-46c3-a26f-98a9a7d61d0e"
+```
+
+The ETag **must** be provided by the server on output, and values **should**
+conform to [RFC 7232][]. Resources **must** support the `If-Match` header (and
+**may** support the `If-None-Match` header) if and only if resources provide
+the ETag.
+
+**Note:** ETag values **must** include quotes as described in [RFC 7232][]. For
+example, a valid ETag is `"foo"`, not `foo`.
+
+ETags **must** be based on an opaque checksum or hash of the resource that
+guarantees it will change if the resource changes.
+
+### Condition headers
+
+If the service receives a request to modify a resource that includes an
+`If-Match` header, the service **must** validate that the value matches the
+current ETag. If the `If-Match` header value does not match the ETag, the
+service **must** reply with an HTTP 412 error.
+
+If the user omits the `If-Match` header, the service **should** permit the
+request. However, services with strong consistency or parallelism requirements
+**may** require users to send ETags all the time and reject the request with an
+HTTP 400 error if it does not contain an ETag.
+
+If any conditional headers are supported for any operation within a service,
+the same conditional headers **must** be supported for all mutation methods
+(`POST`, `PATCH`, `PUT`, and `DELETE`) of any path that supports them, and
+**should** be supported uniformly for all operations across the service.
+
+If any validator or conditional headers are supported for any operations in the
+service, the use of unsupported conditional headers **must** result in an
+error. (In other words, once a service gives the client reason to believe it
+understands conditional headers, it **must not** ever ignore them.)
+
+### Read requests
+
+If a service receives a `GET` or `HEAD` request with an `If-Match` header, the
+service **must** proceed with the request if the ETag matches, or send a
+`412 Precondition Failed` error if the ETag does not match.
+
+If a service receives a `GET` or `HEAD` request with an `If-None-Match` header,
+the service **must** proceed with the request if the ETag does not match, or
+return a `304 Not Modified` response if the ETag does match.
+
+### Strong and weak ETags
+
+ETags can be either "strongly validated" or "weakly validated":
+
+- A strongly validated ETag means that two resources bearing the same ETag are
+  byte-for-byte identical.
+- A weakly validated ETag means that two resources bearing the same ETag are
+  equivalent, but may differ in ways that the service does not consider to be
+  important.
+
+Resources **may** use either strong or weak ETags, as it sees fit, but
+**should** document the behavior. Additionally, weak ETags **must** have a `W/`
+prefix as mandated by [RFC 7232][]:
+
+```
+200 OK
+Content-type: application/json
+ETag: W/"55cc0347-66fc-46c3-a26f-98a9a7d61d0e"
+```
+
+Strong ETags **must** and weak ETags **should** be guaranteed to change if any
+properties on the resource change that are directly mutable by the client.
+Additionally, strong ETags **should** be guaranteed to change if the resource's
+representation changes in a meaningful way (meaning the new representation is
+not equivalent to the old one).
+
+## Further reading
+
+- For how to retry on errors in client libraries, see AIP-194.
+
+## Changelog
+
+- **2020-09-02**: Clarified that other errors may take precedence over
+  `FAILED_PRECONDITION` for ETag mismatches.
+- **2020-09-02**: Add guidance for ETags on request messages.
+- **2019-09-23**: Changed the title to "resource freshness validation".
+
+[rfc 7232]: https://tools.ietf.org/html/rfc7232#section-2.3

aip/general/0154/aip.yaml

@@ -0,0 +1,7 @@
+---
+id: 154
+state: approved
+created: 2019-07-24
+placement:
+  category: design-patterns
+  order: 30