Add terminology for Declarative clients (#1186)

Rename IaC to a clearer term declarative clients, rename all references --------- Co-authored-by: Yusuke Tsutsumi <yusuke@tsutsumi.io>
aip-dev · Aug 4, 2023 · f420852 · f420852
1 parent e6d1b76
commit f420852
Show file tree

Hide file tree

Showing 5 changed files with 29 additions and 24 deletions.
diff --git a/aip/general/0009.md b/aip/general/0009.md
@@ -111,7 +111,7 @@ Examples of clients include the following:
 - Libraries, such as an SDK for a particular programming language
 - Scripts that operates on a JSON representation of a resource after reading it
   from an API
-- Tools, such as an [IaC][] client
+- Tools, such as a [Declarative client][]
 - Visual UIs, such as a web application
 
 ### Google API
@@ -120,14 +120,18 @@ A Network API exposed by a Google service. Most of these are hosted on the
 `googleapis.com` domain. It does not include other types of APIs, such as client
 libraries and SDKs.
 
-### IaC
+### Declarative Clients
 
-Short for Infrastructure-as-code, IaC describes a category of clients that
-consumes a markup language or code that represents resources exposed by an API,
-and executes the appropriate imperative actions to drive the resource to that
-desired state.
+Declarative Clients, also known as Infrastructure as Code (IaC), describes a
+category of clients that consumes a markup language or code that represents
+resources exposed by an API, and executes the appropriate imperative actions to
+drive the resource to that desired state. To determine what changes to make and
+if a set of updates was successful a declarative client compares server side
+resource attributes with client defined values. The comparison feature ensures
+accuracy of a creation or an update but it requires services to treat the client
+set fields as read-only and diligently preserve those values.
 
-Examples of complexities that IaC clients abstract away include:
+Examples of complexities that declarative clients abstract away include:
 
 - Determing the appropriate imperative action (create / update / delete) to
   achieve desired state.
@@ -147,10 +151,11 @@ An API that operates across a network of computers. Network APIs communicate
 using network protocols including HTTP, and are frequently produced by
 organizations separate from those that consume them.
 
-[IaC]: #iac
+[Declarative clients]: #declarative-clients
 [Terraform]: https://www.terraform.io/
 
 ## Changelog
 
+- **2023-07-24**: Rename IaC to Declarative Clients
 - **2023-04-01**: Adding definition of IaC
 - **2023-03-24**: Reformatting content to include anchor links.
diff --git a/aip/general/0111.md b/aip/general/0111.md
@@ -61,7 +61,7 @@ specified in the other AIPs ([AIP-131][] through [AIP-135][]).
 
 ### Major distinctions between management and data plane
 
-- [IaC][] tools operate on the management plane exclusively.
+- [Declarative clients][] operate on the management plane exclusively.
 - Data planes are often on the critical path of user-facing functionality, and
   therefore:
   - Have higher availabilty requirements than management planes.
@@ -71,7 +71,7 @@ specified in the other AIPs ([AIP-131][] through [AIP-135][]).
 
 [AIP-131]: ./0131.md
 [AIP-135]: ./0136.md
-[IaC]: ./0009.md#iac
+[Declarative clients]: ./0009.md#declarative-clients
 
 ## Changelog
 

diff --git a/aip/general/0130.md b/aip/general/0130.md
@@ -21,7 +21,7 @@ The following enumerates multiple categories of methods that exist, often
 grouped up under some object (e.g. collection or resource) that the method
 operates upon.
 
-| Category Name                      | Description                                                                                                                                                                                                   | Related AIPs                                       | [IaC][] integration             | CLI integration | UI integration | SDK integration |
+| Category Name                      | Description                                                                                                                                                                                                   | Related AIPs                                       | [Declarative client][] integration             | CLI integration | UI integration | SDK integration |
 | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ------------------------------- | --------------- | -------------- | --------------- |
 | **Standard Methods**               |                                                                                                                                                                                                               |                                                    |                                 |                 |                |                 |
 | Standard collection methods        | Operate on a collection of resources (List or Create).                                                                                                                                                        | [AIP-121][], [AIP-132][], [AIP-133][]              | automatable                     | automatable     | automatable    | automatable     |
@@ -55,7 +55,7 @@ in the following order:
 ## Rationale
 
 Resource-oriented standard and custom methods are recommended first, as they can
-be expressed in the widest variety of clients (IaC, CLIs, UIs, and so on), and
+be expressed in the widest variety of clients (Declarative clients, CLIs, UIs, and so on), and
 offer the most uniform experience that allows users to apply their knowledge of
 one API to another.
 
@@ -64,7 +64,7 @@ resource or collection) offer a lesser, but still valuable level of consistency,
 helping the user reason about the scope of the action and the object whose
 configuration is read to inform that action. Although mutative custom methods
 are not uniform enough to have a automated integration with exclusively
-resource-oriented clients such as [IaC][] clients, they are still a pattern that
+resource-oriented clients such as [Declarative client][]s, they are still a pattern that
 can easily recognized by CLIs, UIs, and SDKs.
 
 If one cannot express their APIs in a resource-oriented fashion at all, then the
@@ -87,4 +87,4 @@ likely have to be hand-written.
 [AIP-233]: ./0233.md
 [AIP-234]: ./0234.md
 [AIP-235]: ./0235.md
-[IaC]: ./0009.md#IaC
+[Declarative client]: ./0009.md#declarative-clients
diff --git a/aip/general/0133.md b/aip/general/0133.md
@@ -135,7 +135,7 @@ Exceptional cases should have the following behavior:
 
 - The data plane resource allows identical records without a need to
   disambiguate between the two (e.g. rows in a table with no primary key).
-- The data plane resource will not be exposed in [IaC][] clients.
+- The data plane resource will not be exposed in [Declarative clients][].
 
 An API
 **may** allow the `{resource}_id` field have the [field_behavior][] `OPTIONAL`,
@@ -187,12 +187,12 @@ NOT_FOUND errors][permission-denied].
 
 ### Requiring user-specified ids
 
-[IaC][] clients use the resource ID as a way to identify a resource for applying
-updates and for conflict resolution. The lack of a user-specified ID means a
-client is unable to find the resource unless they store the identifier locally,
-and can result in re-creating the resource. This in turn has a downstream effect
-on all resources that reference it, forcing them to update to the the ID of the
-newly-created resource.
+[Declarative clients][] use the resource ID as a way to identify a resource for
+applying updates and for conflict resolution. The lack of a user-specified ID
+means a client is unable to find the resource unless they store the identifier
+locally, and can result in re-creating the resource. This in turn has a
+downstream effect on all resources that reference it, forcing them to update to
+the the ID of the newly-created resource.
 
 Having a user-specified ID also means the client can precalculate the resource
 name and use it in references from other resources.
@@ -207,7 +207,7 @@ name and use it in references from other resources.
 [Management Plane]: ./0111.md#management-plane
 [errors]: ./0193.md
 [field_behavior]: ./203.md
-[IaC]: ./0009.md#iac
+[Declarative clients]: ./0009.md#declarative-clients
 [permission-denied]: ./0193.md#permission-denied
 
 ## Changelog

diff --git a/aip/general/0203.md b/aip/general/0203.md
@@ -207,7 +207,7 @@ behavior when initially authoring of the API.
 Modifying field behavior after initial authoring can result in
 backwards-incompatible changes in clients. For example, making an optional field
 required results in backwards-incompatible changes in the method signature of an
-RPC or a resource in an [IaC][] client. See the
+RPC or a resource in a [Declarative client][]. See the
 [Backwards compatibility](#backwards-compatibility) section for more detailed
 compatibility guidance.
 
@@ -227,7 +227,7 @@ surpass the costs to clients and API users of not doing so.
 [aip-134]: ./0134.md
 [aip-180]: ./0180.md
 [google.api.FieldBehavior]: https://github.com/googleapis/googleapis/blob/master/google/api/field_behavior.proto#L49
-[IaC]: ./0009.md#iac
+[Declarative client]: ./0009.md#declarative-clients
 
 ## Changelog