Skip to content

Commit b5e24a2

Browse files
toumorokoshinoahdietz
toumorokoshi
and
noahdietz
authored
feat(AIP-130): adding method AIP (#1059)
There's a lot of confusion around the types of methods that are possible to service teams, as well as which ones they should be using. This is the start of an AIP to try to codify that a bit better. The AIP starts in draft state, as I think it needs more vetting and time to determine if the terminology is correct. At the same time, there is value in adding them to the main AIPs so that they are more visible and we can contribute incremental improvements. This is not comprehensive, and is meant to reach some agreement on the general structure of the AIP. Co-authored-by: Noah Dietz <noahdietz@users.noreply.github.com>
1 parent 5c16e06 commit b5e24a2

2 files changed

Lines changed: 107 additions & 0 deletions

File tree

‎aip/general/0009.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,12 +108,29 @@ A Network API exposed by a Google service. Most of these are
108108
hosted on the `googleapis.com` domain. It does not include other types of APIs,
109109
such as client libraries and SDKs.
110110

111+
### IaC
112+
113+
Short for Infrastructure-as-code, IaC describes a category of clients that
114+
consumes a markup language or code that represents resources exposed by an API,
115+
and executes the appropriate imperative actions to drive the resource to that
116+
desired state.
117+
118+
Examples of complexities that IaC clients abstract away include:
119+
120+
- Determing the appropriate imperative action (create / update / delete) to achieve desired state.
121+
- Ordering of these imperative actions.
122+
123+
[Terraform][] is an example of such a client.
124+
111125
### Network API
112126

113127
An API that operates across a network of computers. Network APIs
114128
communicate using network protocols including HTTP, and are frequently produced
115129
by organizations separate from those that consume them.
116130

131+
[Terraform]: https://www.terraform.io/
132+
117133
## Changelog
118134

135+
- **2023-04-01**: Adding definition of IaC
119136
- **2023-03-24**: Reformatting content to include anchor links.

‎aip/general/0130.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
---
2+
id: 130
3+
state: draft
4+
created: 2023-03-313
5+
updated: 2023-03-313
6+
placement:
7+
category: operations
8+
order: 9
9+
---
10+
11+
# Methods
12+
13+
An API is composed of one or more methods, which represent a specific operation
14+
that a service can perform on behalf of the consumer.
15+
16+
## Guidance
17+
18+
### Categories of Methods
19+
20+
The following enumerates multiple categories of methods that exist, often
21+
grouped up under some object (e.g. collection or resource) that the method
22+
operates upon.
23+
24+
| Category Name | Description | Related AIPs | [IaC][] integration | CLI integration | UI integration | SDK integration |
25+
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ------------------------------- | --------------- | -------------- | --------------- |
26+
| **Standard Methods** | | | | | | |
27+
| Standard collection methods | Operate on a collection of resources (List or Create). | [AIP-121][], [AIP-132][], [AIP-133][] | automatable | automatable | automatable | automatable |
28+
| Standard resource methods | Fetch or mutate a single resource (Get, Update, Delete). | [AIP-121][], [AIP-131][], [AIP-134][], [AIP-135][] | automatable | automatable | automatable | automatable |
29+
| Batch resource methods | Fetch or mutate multiple resources in a collection by name. | [AIP-231][], [AIP-233][], [AIP-234][], [AIP-235][] | may be used to optimize queries | automatable | automatable | automatable |
30+
| Aggregated list methods | Fetch or mutate multiple resources of the same type across multiple collections. | [AIP-159][] | not useful nor automable | automatable | automatable | automatable |
31+
| **Custom Fetch Methods** | | | | | | |
32+
| Custom collection fetch methods | Fetch information across a collection that cannot be expressed via a standard method. | [AIP-136][] | handwritten | automatable | automatable | automatable |
33+
| Custom resource fetch methods | Fetch information for a single resource that cannot be expressed via a standard method. | [AIP-136][] | handwritten | automatable | automatable | automatable |
34+
| **Custom Mutation Methods** | | | | | | |
35+
| Backing up a resource | Storing a copy of a resource at a particular point in time. | [AIP-162][] | unused or handwritten | automatable | automatable | automatable |
36+
| Restoring a resource | Setting a resource to a version from a particular point in time. | [AIP-162][] | unused or handwritten | automatable | automatable | automatable |
37+
| Renaming a resource | Modify the resource's name or id while preserving configuration and data. | [AIP-136][] | unused or handwritten | automatable | automatable | automatable |
38+
| Custom collection mutation methods | Perform an imperative operation referencing a collection that may mutate one or more resources within that collection in fashion that cannot be easily achieved by standard methods (e.g. state transitions). | [AIP-136][] | unused or handwritten | automatable | automatable | automatable |
39+
| Custom resource mutation methods | Perform an imperative operation on a resource that may mutate it in a way a standard method cannot (e.g. state transitions). | [AIP-136][] | unused or handwritten | automatable | automatable | automatable |
40+
| **Misc Custom Methods** | | | | | |
41+
| Stateless Methods | A method that has no permanent effect on any data within the API (e.g. translating text) | [AIP-136][] | unused or handwritten | automatable | automatable | automatable |
42+
| **None of the above** | | | | | | |
43+
| Streaming methods | Methods that communicate via client, server, or bi-directional streams. | | handwritten | handwritten | handwritten | automatable |
44+
45+
### Choosing a method category
46+
47+
While designing a method, API authors should choose from the defined categories
48+
in the following order:
49+
50+
1. Standard methods (on collections and resources)
51+
1. Standard batch or aggregate methods
52+
1. Custom methods (on collections, resources, or stateless)
53+
1. Streaming methods
54+
55+
## Rationale
56+
57+
Resource-oriented standard and custom methods are recommended first, as they can
58+
be expressed in the widest variety of clients (IaC, CLIs, UIs, and so on), and
59+
offer the most uniform experience that allows users to apply their knowledge of
60+
one API to another.
61+
62+
If a standard method is unsuitable, then custom methods (that are mounted to a
63+
resource or collection) offer a lesser, but still valuable level of consistency,
64+
helping the user reason about the scope of the action and the object whose
65+
configuration is read to inform that action. Although mutative custom methods
66+
are not uniform enough to have a automated integration with exclusively
67+
resource-oriented clients such as [IaC][] clients, they are still a pattern that
68+
can easily recognized by CLIs, UIs, and SDKs.
69+
70+
If one cannot express their APIs in a resource-oriented fashion at all, then the
71+
operation falls in a category where the lack of uniformity makes it difficult
72+
for any client aside from SDKs to model the operation. This category is
73+
preferred last due to the fact that a user cannot rely on their knowledge of
74+
similar APIs, as well as the issue that integration with many clients will
75+
likely have to be hand-written.
76+
77+
[AIP-121]: ./0121.md
78+
[AIP-131]: ./0131.md
79+
[AIP-132]: ./0132.md
80+
[AIP-133]: ./0133.md
81+
[AIP-134]: ./0134.md
82+
[AIP-135]: ./0135.md
83+
[AIP-136]: ./0136.md
84+
[AIP-159]: ./0159.md
85+
[AIP-162]: ./0162.md
86+
[AIP-231]: ./0231.md
87+
[AIP-233]: ./0233.md
88+
[AIP-234]: ./0234.md
89+
[AIP-235]: ./0235.md
90+
[IaC]: ./0009.md#IaC

0 commit comments

Comments
 (0)