Merge branch 'master' into fix129

aip/auth/4115.md

@@ -51,7 +51,7 @@ is called the mTLS configuration endpoint.
 
 The URL of the MDS's mTLS configuration endpoint is: 
 ```
-http://metadata.google.internal/computeMetadata/v1/googleAutoMtlsConfiguration
+http://metadata.google.internal/computeMetadata/v1/instance/platform-security/auto-mtls-configuration
 ```
 
 The request to the MDS's mTLS configuration endpoint **should** be an HTTP GET request without any 

aip/client-libraries/4231.md

@@ -219,6 +219,19 @@ to the following backwards-compatibility expectations:
   libraries.
 - The addition of a `google.api.resource_reference` annotation on an existing
   field **must** be a backwards-compatible change.
+- Changing a `google.api.resource_reference` from `child_type` to `type`
+  **must** be a backwards-compatible change when the `child_type` referenced
+  has a single `pattern` and the newly referenced `type` is the matching
+  parent resource `pattern` (see the
+  [Referencing other resources](#referencing-other-resources) section for
+  more info).
+- For references that appear in a request, changing from `type` to
+  `child_type` **must** be a backwards-compatible change when the resource
+  `pattern` originally referenced via the `type` is included in the set of
+  possible resource `pattern`s derived through `child_type` resolution (see
+  the above [Multi-pattern resources](#multi-pattern-resources) and
+  [Referencing other resources](#referencing-other-resources) sections for
+  more examples).
 
 Note: The `ORIGINALLY_SINGLE_PATTERN` and `FUTURE_MULTI_PATTERN` flags are
 deprecated, and must not be used.
@@ -230,6 +243,7 @@ deprecated, and must not be used.
 
 ## Changelog
 
+- **2023-03-25**: Include compatibility guidance for `type` and `child_type`.
 - **2022-10-28**: Pattern variables are considered final
 - **2020-09-14**: Disallow simultaneous use of both `type` and `child_type`.
 - **2020-05-14**: Added complex resource ID path segments.

aip/client-libraries/4235.md

@@ -7,17 +7,17 @@ created: 2024-03-07
 # Automatically populate fields in the request message
 
 For APIs that leverage request idempotency as described via [AIP-155], APIs may
-choose to have the client libraries automatically populate the `request_id`
-if it is not already set by the customer.
+choose to have the client libraries automatically populate fields such as
+`request_id` if they are not already set by the customer.
 
 **Note:** This feature is primarily written for `request_id` fields within the
 request message. Nonetheless, this feature **must** work for a field of any
-name, as long as the below conditions hold true.
+name, as long as the conditions below hold true.
 
 ## Guidance
 
 APIs **may** configure fields in the request message for automatic population.
-For a field to be automatically populated, **all** the below configurations
+For a field to be automatically populated, **all** the conditions below
 **must** be true:
 
 - The field **must** be of type `string`
@@ -37,19 +37,27 @@ For a field to be automatically populated, **all** the below configurations
 If the aforementioned requirements are met for a given field, client library
 generators **must** enable automatic population of said field in the
 generated client.
+
+The field **must** be automatically populated if and only if one of the
+following conditions holds:
+
+- The field supports explicit presence, and has **not** been set by the user
+- The field doesn't support explicit presence, and its value is the empty
+  string (i.e. the default value)
+
 If a field is specified in the `auto_populated_fields`, but does not meet the
 structural requirements, the client library generators **must not** enable
 automatic population for that field. Client library generators **may** emit an
 error during generation.
 
 Client libraries **must** reuse automatically populated values for retries of
-the same request i.e., the automatically populated fields **must not** be
-regenerated for each RPC attempt with a single request message.
+the same request. In other words, the automatically populated fields
+**must not** be regenerated for each RPC attempt with the same request message.
 
 [AIP-155]: https://google.aip.dev/155
 
 [apf]: https://github.com/googleapis/googleapis/blob/master/google/api/client.proto
 
 [uuid4]: https://google.aip.dev/202#uuid4
 
-[required]: https://google.aip.dev/203#required
+[required]: https://google.aip.dev/203#required

aip/client-libraries/4236.md

@@ -0,0 +1,53 @@
+---
+id: 4236
+state: reviewing
+created: 2024-05-16
+---
+
+# Version-aware clients
+
+APIs can annotate services with [`google.api.api_version`][]. If
+`google.api.api_version` is specified, version-aware clients **must**
+include the value of `google.api.api_version` in the request to the API.
+
+### Expected Generator and Client Library Behavior
+
+If a service is annotated with `google.api.api_version`, client library
+generators **must** include either an HTTP query parameter `$apiVersion`
+or HTTP header `X-Goog-Api-Version`, but a request **must not** contain both.
+
+Generated documentation for a given service **may** include the value of
+`google.api.api_version`, if it exists in the source protos.
+
+Clients **must** treat the value of `google.api.api_version` as opaque to ensure
+robust compatibility.  This means that the specific format or structure of the
+version string **must not** be parsed or interpreted for any purpose beyond identifying
+the intended API version.
+
+## Rationale
+
+### Necessity for Versioning
+
+Explicit API versioning using the `google.api.api_version` annotation is essential
+for maintaining compatibility between clients and services over time. As services
+evolve, their schemas and behaviors may change. By specifying the API version, a
+client communicates its expectations to the service. This allows the service to
+respond in a manner consistent with the client's understanding, preventing errors
+or unexpected results due to incompatible changes.
+
+### Importance of Opaque Treatment
+
+Treating the `google.api.api_version` value as opaque is important for ensuring robust
+compatibility guarantees. By relying on this opaque identifier, clients avoid making
+assumptions about the underlying versioning scheme, which may change independently of
+the API itself. This flexibility allows service providers to evolve their versioning
+strategies without impacting client compatibility.
+
+### Mutual Exclusivity of Query and Header
+
+Both the query parameter and header mechanisms exist to provide flexibility for different
+client environments. However, allowing both simultaneously could lead to ambiguity if the
+values differ. To ensure consistent version identification and prevent potential conflicts,
+only one mechanism should be used at a time.
+
+[`google.api.api_version`]: https://github.com/googleapis/googleapis/blob/master/google/api/client.proto

aip/general/0001.md

@@ -68,12 +68,6 @@ digraph d_front_back {
 }
 ```
 
-### Technical leads
-
-The current TL (technical lead) for APIs is Eric Brewer; he has delegated some
-responsibilities for API Design to the API Design TL (Andrei Scripniciuc
-([@andreisc][])).
-
 As noted in the diagram above, the TL is the final decision-maker on the AIP
 process and the final point of escalation if necessary.
 
@@ -86,14 +80,12 @@ and these Googlers will be approvers for each AIP in the general scope.
 
 The list of AIP editors is currently:
 
-- Andrei Scripniciuc ([@andrei-scripniciuc][])
 - Angie Lin ([@alin04][])
-- Brian Grant ([@bgrant0607][])
-- Hami Asaadi ([@hrasadi][])
 - Jon Skeet ([@jskeet][])
 - Jose Juan Zavala Iglesias ([@itsStrobe][])
 - Louis Dejardin ([@loudej][])
 - Noah Dietz ([@noahdietz][])
+- Sam Levenick ([@slevenick][])
 - Sam Woodard ([@shwoodard][])
 
 The editors are also responsible for the administrative and editorial aspects
@@ -270,6 +262,7 @@ state, and will link to the new, current AIP.
 
 ## Changelog
 
+- **2024-09-04**: Updated names of current editors and remove TLs.
 - **2023-05-10**: Updated names of current and editors and TLs.
 - **2019-07-30**: Further clarified AIP quorum requirements.
 - **2019-05-12**: Collapsed AIP approvers and editors into a single position,
@@ -280,11 +273,9 @@ state, and will link to the new, current AIP.
 [aip github repository]: https://github.com/googleapis/aip
 [open an issue]: https://github.com/googleapis/aip/issues
 [@alin04]:https://github.com/alin04
-[@bgrant0607]: https://github.com/bgrant0607
-[@hrasadi]: https://github.com/hrasadi
 [@jskeet]: https://github.com/jskeet
 [@loudej]: https://github.com/loudej
 [@noahdietz]: https://github.com/noahdietz
+[@slevenick]: https://github.com/slevenick
 [@shwoodard]: https://github.com/shwoodard
-[@andrei-scripniciuc]: https://github.com/andrei-scripniciuc
 [@itsStrobe]: https://github.com/itsStrobe

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/0100.md

@@ -268,7 +268,7 @@ A few tips:
 
 ### ...if one of my API reviewers is unresponsive?
 
-Reach out to the reviewer on Hangouts. If that fails, reach out to the other
+Reach out to the reviewer on Chat. If that fails, reach out to the other
 reviewer, who will coordinate accordingly. If that fails also, escalate
 according to [AIP-1][].
 

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
@@ -97,16 +97,16 @@ patterns, such as database transactions, import and export, or data analysis.
 ### Strong Consistency
 
 For methods that operate on the [management plane][], the completion of those
-operations (either successful or with an error, LRO or synchronous) **must**
-mean that the state of the resource's existence and all user-settable values
-have reached a steady-state.
+operations (either successful or with an error, long-running operation, or
+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:
 
-- Following a successful create that is is latest mutation on a resource, a get
+- Following a successful create that is the latest mutation on a resource, a get
   request for a resource **must** return the resource.
 - Following a successful update that is the latest mutation on a resource, a get
   request for a resource **must** return the final values from the update
@@ -142,9 +142,10 @@ have sole responsibility and authority for maintaining the application state.
 
 ### Cyclic References
 
-The relationship between resources, such as parent-child or
-[resource references][], **must** be representable via a
-[directed acyclic graph][].
+The relationship between resources, such as with [resource references][],
+**must** be representable via a [directed acyclic graph][]. The parent-child
+relationship also **must** be acyclic, and as per [AIP-124][] a given resource
+instance will only have one canonical parent resource.
 
 A cyclic relationship between resources increases the complexity of managing
 resources. Consider resources A and B that refer to
@@ -161,6 +162,7 @@ This requirement does not apply to relationships that are expressed via
 [output only][] fields, as they do not require the user to specify the values
 and in turn do not increase resource management complexity.
 
+[AIP-124]: ./0124.md
 [create]: ./0133.md
 [custom methods]: ./0136.md
 [delete]: ./0135.md
@@ -181,10 +183,11 @@ and in turn do not increase resource management complexity.
 
 ## Changelog
 
+- **2024-07-08**: Clarify acyclic nature of parent-child relationship.
 - **2023-08-24**: Added guidance on consistency guarantees of methods.
 - **2023-07-23**: Clarify stateless protocol definition.
 - **2023-01-21**: Explicitly require matching schema across standard methods.
 - **2022-12-19**: Added a section requiring Get and List.
 - **2022-11-02**: Added a section restricting resource references.
 - **2019-08-01**: Changed the examples from "shelves" to "publishers", to
-  present a better example of resource ownership.
+  present a better example of resource ownership.

aip/general/0122.md

@@ -99,11 +99,28 @@ An API **should** use the less-redundant form:
 users/vhugo1802/events/birthday-dinner-226
 ```
 
-In this situation, the _message_ is still called `UserEvent`; only the resource
-name is shortened.
+In this situation, the _message_ and _resource type_ are still called
+`UserEvent`; only the collection and resource identifiers in the pattern(s) are 
+shortened. Since the _resource type_ is not shortened, the `singular` and
+`plural` are similarly _not shortened_.
+
+```
+message UserEvent {
+  option (google.api.resource) = {
+    type: "example.googleapis.com/UserEvent"
+    // Only the collection & resource identfiers in the `pattern` are shortened.    
+    pattern: "projects/{project}/users/{user}/events/{event}"
+    singular: "userEvent"
+    plural: "userEvents"
+  };
+
+  string name = 1;
+}
+```
 
 **Note:** APIs wishing to do this **must** follow this format consistently
-throughout the API, or else not at all.
+throughout all of its `pattern` entries defined and anywhere else the
+resource is referenced in the API, or else not at all.
 
 ### Resource ID segments
 
@@ -335,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
@@ -357,6 +402,10 @@ 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.
 - **2023-09-01**: Add a clause that allows embedding for revision resource
   messages.