Merge branch 'master' into bshaffer-patch-1

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

@@ -18,85 +18,90 @@ The following terminology **should** be used consistently throughout AIPs.
 
 ### API
 
-Application Programming Interface. This can be a local interface (such as a
+Application programming interface. This can be a local interface (such as a
 client library) or a Network API (defined below).
 
-### API Backend
+### API backend
 
 A set of servers and related infrastructure that implements the business logic
-for an API Service. An individual API backend server is often called an API
+for an API service. An individual API backend server is often called an API
 server.
 
-### API Consumer
+### API consumer
 
-The entity that consumes an API Service. For Google APIs, it typically is a
+The entity that consumes an API service. For Google APIs, it typically is a
 Google project that owns the client application or the server resource.
 
-### API Definition
+### API definition
 
 The definition of an API, usually defined in a Protocol Buffer service. An API
-Definition can be implemented by any number of API Services.
+definition can be implemented by any number of API services.
 
-### API Frontend
+### API frontend
 
 A set of servers plus related infrastructure that provides common functionality
-across API Services, such as load balancing and authentication. An individual
+across API services, such as load balancing and authentication. An individual
 API frontend server is often called an API proxy.
 
 **Note:** the API frontend and the API backend may run next to each other or far
 away from each other. In some cases, they can be compiled into a single
 application binary and run inside a single process.
 
-### API Method
+### API method
 
 An individual operation within an API. It is typically represented in Protocol
 Buffers by an `rpc` definition, and is mapped to a function in the API in most
 programming languages.
 
-### API Producer
+### API producer
 
-The entity that produces an API Service. For Google APIs, it typically is a
-Google team responsible for the API Service.
+The entity that produces an API service. For Google APIs, it typically is a
+Google team responsible for the API service.
 
-### API Product
+### API product
 
-An API Service and its related components, such as Terms of Service,
+An API service and its related components, such as Terms of Service,
 documentation, client libraries, and service support, are collectively presented
-to customers as a API Product. For example, Google Calendar API.
+to customers as a API product. For example, Google Calendar API.
 
-**Note:** people sometimes refer to an API Product simply as an API.
+**Note:** people sometimes refer to an API product simply as an API.
 
-### API Service
+### API service
 
 A deployed implementation of one or more APIs, exposed on one or more network
 addresses, such as the Cloud Pub/Sub API.
 
-### API Service Definition
+### API service definition
 
-The combination of API Definitions (`.proto` files) and API Service
-configurations (`.yaml` files) used to define an API Service. The schema for
-Google API Service Definition is `google.api.Service`.
+The combination of API definitions (`.proto` files) and API service
+configurations (`.yaml` files) used to define an API service. The schema for
+Google API service definition is `google.api.Service`.
 
-### API Service Endpoint
+### API service endpoint
 
-Refers to a network address that an API Service uses to handle incoming API
-Requests. One API Service may have multiple API Service Endpoints, such as
+Refers to a network address that an API service uses to handle incoming API
+requests. One API service may have multiple API service endpoints, such as
 `https://pubsub.googleapis.com` and `https://content-pubsub.googleapis.com`.
 
-### API Service Name
+### API service name
 
-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`.
+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 Request
+### API title
 
-A single invocation of an API Method. It is often used as the unit for billing,
+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,
 logging, monitoring, and rate limiting.
 
-### API Version
+### API version
 
 The version of an API or a group of APIs if they are defined together. An API
-Version is often represented by a string, such as "v1", and presents in API
+version is often represented by a string, such as "v1", and presents in API
 requests and Protocol Buffers package names.
 
 ### Client
@@ -156,6 +161,8 @@ organizations separate from those that consume them.
 
 ## Changelog
 
+- **2024-12-18**: Downcase headings and terms as per dev docs style
+- **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
@@ -101,8 +101,8 @@ 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][].
+[Output only][] values unrelated to the resource [state][] **should** also have
+reached a steady-state for values that are related to the resource [state][].
 
 Examples include:
 
@@ -121,8 +121,8 @@ ensuring that resources immediately reflect steady user state after an operation
 is complete ensures clients can rely on method completion as a signal to begin
 the next operation.
 
-[output only][] fields ideally would follow the same guidelines, but as
-these fields can often represent a resources live state, it's sometimes
+[Output only][] fields ideally would follow the same guidelines, but as
+these fields can often represent a resource's live state, it's sometimes
 necessary for these values to change after a successful mutation operation to
 reflect a state change.
 

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

@@ -28,15 +28,15 @@ In the guidance below, we use the following terms:
   This usually (but not necessarily) matches the hostname that users use to
   call the service. Example: `pubsub.googleapis.com`. This is equivalent to an
   [API Group][] in Kubernetes.
-- **Type:** This is the name used for the type within the API. This *should*
-  match the name of the protobuf message. This is equivalent to an [Object][] in
-  Kubernetes.
+- **Type:** This is the name used for the type within the API e.g. the name of
+  the Protobuf `message`. This is equivalent to an [Object][] in Kubernetes.
 
 ## Guidance
 
 APIs **must** define a resource type for each resource in the API, according to
 the following pattern: `{Service Name}/{Type}`. The type name **must**:
 
+- Match the containing API type's name.
 - Start with an uppercase letter.
 - Only contain alphanumeric characters.
 - Be of the singular form of the noun.
@@ -104,6 +104,15 @@ resource:
 
 ## Rationale
 
+### Type and message name alignment
+
+In addition to simple schema-resource coherence and alignment, a number of
+consumers benefit from the `{Type}` and `message` names matching. Consumers have
+simpler lookups, client libraries get the same in addition to aligned user
+experience where resource-oriented code has naming aligned with the generated
+`message` code, generated reference documentation aligns resources with
+`message` docs, etc.
+
 ### Singular and Plural
 
 Well-defined singular and plurals of a resource enable clients to determine the
@@ -124,6 +133,7 @@ such as UpperCamelCase and snake_case.
 
 ## Changelog
 
+- **2025-01-09**: Strongly align resource type and message naming.
 - **2024-08-07**: Added multi-pattern ordering compatibility requirements.
 - **2023-09-19**: Prohibited duplicate pattern variables.
 - **2023-05-06**: Added requirement of singular and plural.

aip/general/0129.md

@@ -67,15 +67,15 @@ field's name.
 
 For user-specified fields, the value in response from the service **must** be
 the same as provided by the create or update request. For string fields this
-means returning the value unchanged, with one exception: 
+means returning the value unchanged, with one exception:
 
 * When a string field has a data type annotation, a normalized string that
   represents the given value **may** be returned.
 
 ### 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/0134.md

@@ -105,6 +105,11 @@ message UpdateBookRequest {
     populated (have a non-empty value).
   - Update masks **must** support a special value `*`, meaning full replacement
     (the equivalent of `PUT`).
+    - API producers need to be conscious of how adding new, mutable fields to a
+      resource will be handled when consumers use `*` without knowledge of said
+      new, mutable fields. Likewise consumers need to use `*` only when the
+      risks of doing so are acceptable. In general, it is safest to explicitly
+      specify the fields to update rather than use `*`.
 - The request message **must not** contain any other required fields, and
   **should not** contain other optional fields except those described in this
   or another AIP.
@@ -297,6 +302,7 @@ does not exist, the service **must** error with `NOT_FOUND` (HTTP 404) unless
 
 ## Changelog
 
+- **2024-12-03**: Add caveats to usage of full replacement `update_mask`.
 - **2024-03-14**: Make `update_mask` optional field_behaviour guidance a **must**.
 - **2023-08-26**: Adding consistency requirement.
 - **2023-07-17**: Make `update_mask` name guidance a **must**.

aip/general/0136.md

@@ -157,6 +157,14 @@ read data have first-class concepts in some clients (DataSources in
 Terraform) and clearly indicate to a user which methods can be called
 without risk of runtime impact.
 
+### Disallowing prepositions
+
+Generally, method names with prepositions indicate that a new method is being
+used where a field should instead be added to an existing method, or the method
+should use a distinct verb. For example, if a `CreateBook` message already
+exists and you are considering adding `CreateBookFromDictation`, consider a `TranscribeBook` method instead. Similarly, if there is desire for a
+property-specific look-up method, instead of `GetBookByAuthor` consider a
+`SearchBooks` with an `author` field as a search dimension.
 
 [get]: ./0131.md
 [list]: ./0132.md
@@ -177,6 +185,7 @@ languages.
 
 ## Changelog
 
+- **2025-01-09:** Add original rationale for disallowing prepositions in names.
 - **2023-11-16:** Included link to AIP-127 "HTTP and gRPC Transcoding" for guidance on body definition.
 - **2023-05-16:** Added prohibition of the term "async" within RPC names.
 - **2023-05-09:** Adding guidance for POST and GET, require parent instead of