feat: AIP-128 – Declarative-friendly interfaces

Author: Luke Sneeringer

aip/general/0128/aip.md.j2

@@ -0,0 +1,116 @@
+# Declarative-friendly interfaces
+
+Many services need to interact with common DevOps tools, particularly those
+that create and manage network-addressible resources (such as virtual machines,
+load balancers, database instances, and so on). These tools revolve around the
+principle of "configuration as code": the user specifies the complete intended
+landscape, and tooling is responsible for making whatever changes are necessary
+to achieve the user's specification.
+
+These tools are **declarative**: rather than specifying specific _actions_ to
+take, they specify the desired _outcome_, with the actions being derived based
+on the differences between the current landscape and the intended one.
+
+Furthermore, there are numerous popular DevOps tools, with more being
+introduced each year. Integrating hundreds of resource types with multiple
+tools requires strong consistency, so that integration can be automated.
+
+## Guidance
+
+Services **should** clearly delineate between "control plane" operations and
+"data plane" operations, ideally through the use of distinct services with
+their own interface definition documents.
+
+- Control plane operations are responsible for managing the _lifecycle_ of
+  resources.
+- Data plane operations are responsible for managing the _content_ of
+  resources.
+
+The same resource **may** have both control plane operations and data plane
+operations associated with it. For example, a database API would have
+operations to create or delete database tables (control plane) as well as
+operations to write and read rows to that table (data plane).
+
+### Resources
+
+Resources that are declarative-friendly **must** use only strongly-consistent
+standard methods for managing resource lifecycle, which allows tools to support
+these resources generically, as well as conforming to other
+declarative-friendly guidance (see [further reading](#further-reading)).
+
+Declarative-friendly resources **should** designate that they follow the
+declarative-friendly style:
+
+{% tab proto %}
+
+{% sample 'declarative_friendly.proto', 'message Book' %}
+
+{% tab oas %}
+
+{% sample 'declarative_friendly.oas.yaml', 'schema' %}
+
+{% endtabs %}
+
+### Annotations
+
+Declarative-friendly resources **must** include a `annotations` field to allow
+clients to store small amounts of arbitrary data:
+
+```typescript
+// A representation of a single book.
+interface Book {
+  // The name of the book.
+  // Format: publishers/{publisher}/books/{book}
+  name: string;
+
+  // Other fields...
+
+  // A dictionary of key-value pairs.
+  // This has no effect on the service's behavior, but clients may use it
+  // to persistently store small amounts of information related to this
+  // resource.
+  annotations: { [key: string]: string };
+}
+```
+
+The `annotations` field **must** use the [Kubernetes limits][] to maintain wire
+compatibility, and **should** require dot-namespaced annotation keys to prevent
+tools from trampling over one another.
+
+**Note:** Annotations are distinct from various forms of labels. Labels can be
+used by server-side policies, such as IAM conditions. Annotations exist to
+allow client tools to store their own state information without requiring a
+database.
+
+<!-- prettier-ignore -->
+[kubernetes limits]: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/#syntax-and-character-set
+
+### Reconciliation
+
+If a resource takes time (more than a few seconds) for updates to be realized,
+the resource **should** include a `bool reconciling` field to disclose that
+changes are in flight. This field **must** be output only.
+
+A resource **must** set the `reconciling` field to `true` if the current state
+of the resource does not match the user's intended state, and the system is
+working to reconcile them. This is regardless of whether the root cause of
+going into reconciliation was user or system action.
+
+**Note:** Services responding to a `GET` request **must** return the resource's
+current state (not the intended state).
+
+## Further reading
+
+A significant amount of guidance is more strict for declarative-friendly
+interfaces, due to the focus on automation on top of these resources. This list
+is a comprehensive reference to declarative-friendly guidance in other AIPs:
+
+- Resources **must** use user-settable resource IDs: see AIP-133.
+- Resources **must** permit "create or update": see AIP-134.
+- Resources **should** permit "delete if existing": see AIP-135.
+- Resources **should not** employ custom methods: see AIP-136.
+- Resources **must** use the `Update` method for repeated fields: see AIP-144.
+- Resources **must** include certain standard fields: see AIP-148.
+- Resources **must** have an `etag` field: see AIP-154.
+- Resources **must** provide change validation: see AIP-163.
+- Resources **should** support soft delete: see AIP-164.

aip/general/0128/aip.yaml

@@ -0,0 +1,7 @@
+---
+id: 128
+state: approved
+created: 2020-10-06
+placement:
+  category: resource-design
+  order: 65

aip/general/0128/declarative_friendly.oas.yaml

@@ -0,0 +1,17 @@
+---
+openapi: 3.0.3
+info:
+  title: Library
+  version: 1.0.0
+components:
+  schema:
+    Book:
+      description: A representation of a single book.
+      x-declarative-friendly: true
+      properties:
+        name:
+          type: string
+          description: |
+            The name of the book.
+            Format: publishers/{publisher}/books/{book}
+        # Additional fields...

aip/general/0128/declarative_friendly.proto

@@ -0,0 +1,32 @@
+// Copyright 2020 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+import "google/api/resource.proto";
+
+// A representation of a book.
+message Book {
+  option (google.api.resource) = {
+    type: "library.googleapis.com/Book"
+    pattern: "publishers/{publisher}/books/{book}"
+    style: DECLARATIVE_FRIENDLY
+  };
+
+  // The name of the book.
+  // Format: publishers/{publisher}/books/{book}
+  string name = 1;
+
+  // Other fields...
+}