Merge branch 'master' into aip-193-make-live

aip/general/0009.md

@@ -88,6 +88,11 @@ Requests. One API Service may have multiple API Service Endpoints, such as
 Refers to the logical identifier of an API Service. Google APIs use RFC 1035 DNS
 compatible names as their API Service Names, such as `pubsub.googleapis.com`.
 
+### API Title
+
+Refers to the user-facing product title of an API service, such as "Cloud Pub/Sub
+API".
+
 ### API Request
 
 A single invocation of an API Method. It is often used as the unit for billing,
@@ -156,6 +161,7 @@ organizations separate from those that consume them.
 
 ## Changelog
 
+- **2024-10-23**: Add API Title entry
 - **2023-07-24**: Rename IaC to Declarative Clients
 - **2023-04-01**: Adding definition of IaC
-- **2023-03-24**: Reformatting content to include anchor links.
+- **2023-03-24**: Reformatting content to include anchor links.

aip/general/0121.md

@@ -65,13 +65,13 @@ If the request to or the response from a standard method (or a custom method in
 the same *service*) **is** the resource or **contains** the resource, the
 resource schema for that resource across all methods **must** be the same.
 
-| Standard method | Request               | Response        |
-| --------------- | --------------------- | --------------- |
-| Create          | Contains the resource | Is the resource |
-| Get             | None                  | Is the resource |
-| Update          | Contains the resource | Is the resource |
-| Delete          | None                  | None            |
-| List            | None                  | Is the resource |
+| Standard method | Request               | Response               |
+| --------------- | --------------------- | ---------------------- |
+| Create          | Contains the resource | Is the resource        |
+| Get             | None                  | Is the resource        |
+| Update          | Contains the resource | Is the resource        |
+| Delete          | None                  | None                   |
+| List            | None                  | Contains the resources |
 
 *The table above describes each standard method's relationship to the resource,
 where "None" indicates that the resource neither **is** nor **is contained** in
@@ -102,7 +102,7 @@ synchronous) **must** mean that the state of the resource's existence and all
 user-settable values have reached a steady-state.
 
 [output only][] values unrelated to the resource [state][] **should** also have
-reached a steady-state. for values that are related to the resource [state][].
+reached a steady-state for values that are related to the resource [state][].
 
 Examples include:
 

aip/general/0122.md

@@ -352,6 +352,34 @@ message Book {
 
 ## Rationale
 
+### Using names instead of IDs
+
+For any large system, there are many kinds of resources. To use simple resource
+IDs to identify a resource, we'd actually need use a resource-specific tuple to
+reliably identify it, such as `(bucket, object)` or `(user, album, photo)`. This
+creates several issues:
+
+* Developers have to understand and remember such anonymous tuples.
+* Passing tuples is generally harder than passing strings.
+* Centralized infrastructures, such as logging and access control systems,
+  don't understand specialized tuples.
+* Specialized tuples limit API design flexibility, such as providing
+  reusable API interfaces. For example,
+  [Long Running Operations][aip-151] can work with many other API interfaces
+  because they use flexible resource names.
+
+[aip-151]: ./0151.md
+
+### Standardizing on `name`
+
+The concept of resource names is not a new one, and is formalized in Uniform
+Resource Names (URN) in conjunction with Uniform Resource Identifiers (URI) and
+Uniform Resource Locators (URL). Considering that the term "name" is so heavily
+overloaded in general, usage outside of a very well-defined meaning would be
+confusing for developers. So, the field name `name` is reserved in the context
+of AIP-compliant APIs so as to eliminate any confusion with resource names, and
+force other would be "name" fields to use a more specific field name.
+
 ### Disallow embedding of resources
 
 Using a resource message directly as the type of a field within another resource
@@ -374,6 +402,8 @@ isolation of logical concerns per-resource.
 
 ## Changelog
 
+- **2024-10-15**: Add some rationale we found for use of `name` as a field and
+  instead of IDs as an identifier.
 - **2024-06-14**: Clarify resource annotation shortening rules for nested
   collections.
 - **2023-09-19**: Prohibit duplicate collection identifiers.

aip/general/0129.md

@@ -75,7 +75,7 @@ means returning the value unchanged, with one exception:
 ### Normalizations
 
 A field that is normalized by the service **must** be annotated with the
-`google.api.field_info` extension. See [AIP-202](aip-202) for guidance on using
+`google.api.field_info` extension. See ([AIP-202][]) for guidance on using
 this extension The allowed set of normalizations includes the following formats:
 
 * uuid

aip/general/0162.md

@@ -272,6 +272,7 @@ needs to be familiar with a second set of retrieval and identifier methods.
 - **2023-09-01**: AIP was updated to be a sub-collection.
 - **2021-04-27**: Added guidance on returning the resource from Delete Revision.
 
+[aip-142]: ./0142.md
 [alias]: ./0122.md#resource-id-aliases
 [cascading delete]: ./0135.md#cascading-delete
 [UUID4]: https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)

aip/general/0164.md

@@ -24,9 +24,10 @@ mark the resource as having been deleted, but not completely remove it from the
 system. If the method behaves this way, it **should** return the updated
 resource instead of `google.protobuf.Empty`.
 
-Resources that support soft delete **should** have a `purge_time` field as
-described in AIP-148. Additionally, resources **should** include a `DELETED`
-state value if the resource includes a `state` field (AIP-216).
+Resources that support soft delete **should** have both a `delete_time` and
+`purge_time` field as described in AIP-148. Additionally, resources **should**
+include a `DELETED` state value if the resource includes a `state` field
+(AIP-216).
 
 ### Undelete
 
@@ -147,6 +148,7 @@ resource is not deleted, the service **must** respond with `ALREADY_EXISTS`
 
 ## Changelog
 
+- **2024-09-24**: Included missing requirement for `delete_time`.
 - **2023-07-13**: Renamed overloaded `expire_time` to `purge_time`.
 - **2021-07-12**: Added error behavior when soft deleting a deleted resource.
 - **2021-07-12**: Clarified that `ALREADY_EXISTS` errors apply to `Undelete`.

aip/general/0185.md

@@ -0,0 +1,184 @@
+---
+id: 185
+state: approved
+created: 2024-10-22
+placement:
+  category: compatibility
+  order: 40
+---
+
+# API Versioning
+
+This topic describes the versioning strategies used by Google APIs. In
+general, these strategies apply to all Google-managed services.
+
+## Guidance
+
+All Google API interfaces **must** provide a _major version number_, which is
+encoded at the end of the protobuf package, and included as the first part of
+the URI path for REST APIs. In the event an API needs to make an incompatible
+change, consult [AIP-180][] and [AIP-181][] for necessary steps based on the
+stability level of the surface in question.
+
+Note: The use of the term "major version number" above is taken from
+[semantic versioning][]. However, unlike in traditional semantic versioning,
+Google APIs **must not** expose minor or patch version numbers. For
+example, Google APIs use `v1`, not `v1.0`, `v1.1`, or `v1.4.2`. From a user's
+perspective, major versions are updated in place, and users receive new
+functionality without migration.
+
+A new major version of an API **must not** depend on a previous major version of
+the same API. An API surface **must not** depend on other APIs, except for in
+the cases outlined in [AIP-213][] and [AIP-215][].
+
+Different versions of the same API **must** be able to work at the same time
+within a single client application for a reasonable transition period. This time
+period allows the client to transition smoothly to the newer version. An older
+version **must** go through a reasonable, well-communicated deprecation period
+before being shut down.
+
+For releases which have [alpha or beta stability][AIP-181], APIs **must** append
+the stability level after the major version number in the protobuf package and
+URI path using one of these strategies:
+
+- Channel-based versioning (recommended)
+- Release-based versioning
+- Visibility-based versioning
+
+### Channel-based versioning
+
+A *stability channel* is a long-lived release at a given stability level that
+receives in-place updates. There is no more than one channel per stability level
+for a major version. Under this strategy, there are up to three channels
+available: alpha, beta, and stable.
+
+The alpha and beta channel **must** have their stability level appended to the
+version, but the stable channel **must not** have the stability level appended.
+For example, `v1` is an acceptable version for the stable channel, but `v1beta`
+or `v1alpha` are not. Similarly, `v1beta` or `v1alpha` are acceptable versions
+for the respective beta and alpha channel, but `v1` is not acceptable for
+either. Each of these channels receives new features and updates "in-place".
+
+The beta channel's functionality **must** be a superset of the stable channel's
+functionality, and the alpha channel's functionality **must** be a superset of
+the beta channel's functionality.
+
+#### Deprecating API functionality
+
+API elements (fields, messages, RPCs) **may** be marked deprecated in any
+channel to indicate that they should no longer be used:
+
+```proto
+// Represents a scroll. Books are preferred over scrolls.
+message Scroll {
+  option deprecated = true;
+
+  // ...
+}
+```
+
+Deprecated API functionality **must not** graduate from alpha to beta, nor beta
+to stable. In other words, functionality **must not** arrive "pre-deprecated"
+in any channel.
+
+The beta channel's functionality **may** be removed after it has been deprecated
+for a sufficient period; we recommend 180 days. For functionality that exists
+only in the alpha channel, deprecation is optional, and functionality **may** be
+removed without notice. If functionality is deprecated in an API's
+alpha channel before removal, the API **should** apply the same annotation, and
+**may** use any timeframe it wishes.
+
+### Release-based versioning
+
+**Important:** This pattern is not commonly used for new services. There are
+existing services that follow it, but Channel-based Versioning is the preferred
+mechanism.
+
+An *individual release* is an alpha or beta release that is expected to be
+available for a limited time period before its functionality is incorporated
+into the stable channel, after which the individual release will be shut down.
+When using release-based versioning strategy, an API may have any number of
+individual releases at each stability level.
+
+Note: Both the channel-based and release-based strategies update the _stable_
+version in-place. There is a single stable channel, rather than individual
+stable releases, even when using the release-based strategy.
+
+Alpha and beta releases **must** have their stability level appended to the
+version, followed by an incrementing release number. For example, `v1beta1` or
+`v1alpha5`. APIs **should** document the chronological order of these versions
+in their documentation (such as comments).
+
+Each alpha or beta release **may** be updated in place with backwards-compatible
+changes. For beta releases, backwards-incompatible updates **should** be made by
+incrementing the release number and publishing a new release with the change.
+For example, if the current version is `v1beta1`, then `v1beta2` is released
+next.
+
+Alpha and beta releases **should** be shut down after their functionality
+reaches the stable channel. An alpha release **may** be shut down at any time,
+while a beta release **should** allow users a reasonable transition period; we
+recommend 180 days.
+
+### Visibility-based versioning
+
+[API visibility][] is an advanced feature provided by Google API infrastructure.
+It allows API producers to expose multiple external API views from one internal
+API surface, and each view is associated with an API _visibility label_, such
+as:
+
+```proto
+import "google/api/visibility.proto";
+
+message Resource {
+  string name = 1;
+
+  // Preview. Do not use this feature for production.
+  string display_name = 2
+    [(google.api.field_visibility).restriction = "PREVIEW"];
+}
+```
+
+A visibility label is a case-sensitive string that can be used to tag any API
+element. By convention, visibility labels should always use UPPER case.
+An implicit `PUBLIC` label is applied to all API elements unless an explicit
+visibility label is applied as in the example above.
+
+Each visibility label is an allow-list. API producers need to grant visibility
+labels to API consumers for them to use API features associated with the labels.
+In other words, an API visibility label is like an ACL'ed API version.
+
+Multiple visibility labels **may** be applied to an element by using a
+comma-separated string (e.g. `"PREVIEW,TRUSTED_TESTER"`). When multiple
+visibility labels are used, then the client needs only _one_ of the visibility
+labels (logical `OR`).
+
+By default, the visibility labels granted to the API consumer are used to verify
+incoming requests. However, a client can send requests with an explicit
+visibility label as follows:
+
+```
+GET /v1/projects/my-project/topics HTTP/1.1
+Host: pubsub.googleapis.com
+Authorization: Bearer y29....
+X-Goog-Visibilities: PREVIEW
+```
+
+A single API request can specify at most one visibility label.
+
+API producers can use API visibility for API versioning, such as
+`INTERNAL` and `PREVIEW`. A new API feature starts with the `INTERNAL` label,
+then moves to the `PREVIEW` label. When the feature is stable and becomes
+generally available, all API visibility labels are removed from the API
+definition.
+
+In general, API visibility is easier to implement than API versioning for
+incremental changes, but it depends on sophisticated API infrastructure support.
+Google Cloud APIs often use API visibility for Preview features.
+
+[AIP-180]: https://aip.dev/180
+[AIP-181]: https://aip.dev/181
+[AIP-213]: https://aip.dev/213
+[AIP-215]: https://aip.dev/215
+[api visibility]: https://github.com/googleapis/googleapis/blob/master/google/api/visibility.proto
+[semantic versioning]: https://semver.org/

aip/general/0192.md

@@ -92,9 +92,22 @@ documentation page containing the diagram as an image.
 
 ### Cross-references
 
-Comments **may** "link" to another component (service, method, message, field,
-enum, or enum value) by using the fully-qualified name of the element as a
-Markdown reference link. For example: `[Book][google.example.v1.Book]`
+A comment can "link" to another component (service, method, message, field,
+enum, or enum value) as a Markdown reference link. The reference **must** be one
+of the following forms:
+
+- The fully-qualified name of the element e.g. `[Book][google.example.v1.Book]`
+- A scope-relative reference qualified e.g. `[Sci-Fi genre][Genre.GENRE_SCI_FI]`
+- An implied reference e.g. `[Book][]` which equates to `[Book][Book]`
+
+These references are resolved as per [name resolution][] rules.
+
+Containing fields names **must not** be used in references. They will not
+resolve. The original definition **must** be referenced instead. For example,
+`[author][Book.author.family_name]` where `author` is a field of `Book`, will
+not resolve, but `[author][Author.family_name]` will.
+
+[name resolution]: https://protobuf.dev/programming-guides/proto3/#name-resolution
 
 ### External links
 
@@ -144,6 +157,7 @@ of inadvertent omissions of the internal content annotation.
 
 ## Changelog
 
+- **2024-10-29**: Include cross-reference resolution rules.
 - **2023-08-11**: Expand deprecated comment requirement to all components.
 - **2021-04-20**: Added guidance for deprecated services and RPCs.
 - **2020-04-01**: Added guidance requiring absolute URLs for external links.