diff --git a/aip/general/0009.md b/aip/general/0009.md index 176189ac9..a48450ab6 100644 --- 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. \ No newline at end of file diff --git a/aip/general/0111.md b/aip/general/0111.md index 4deb0ffec..10df9ec77 100644 --- 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 index 8181e1f1c..c3a10c8be 100644 --- 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 index 871668fc1..b0f13cee9 100644 --- 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 index 3a55a5834..7b95ade88 100644 --- 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