feat(planes): porting AEP-111 from AIP-111 #85
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,71 @@ | ||
| # Planes | ||
|
|
||
| Systems such as software-defined networks and public clouds have distinct sets | ||
| of APIs which are crucial for accomplishing a full user journey. For example, | ||
| in networking, a user must: | ||
|
|
||
| 1. Configure the network to determine how data will flow (e.g. defining network | ||
| interfaces, gateways) | ||
| 2. Send data through the network. | ||
|
|
||
| The API and operations for these steps can be divided into layers known as | ||
| _planes_, indicating the role that the API plays in data. | ||
|
|
||
|
There was a problem hiding this comment. I made a bunch of local suggestions above, but on the whole, I'm confused by the point this is trying to make. The management plane reads and configures resources; the data plan is for reading and writing user data (also "ideally" in the form of resources). I'm not sure that someone with no context could easily categorize APIs into the right plane given these definitions. There was a problem hiding this comment. ...I'm not even sure that I can. Would creating a Facebook group be a management plane or data plane method? The group name/description/etc. are UGC, but if individual posts in the group are part of the data plane then does that place group management in the management plane? If these resources are all in the same API, and APIs as a whole are categorized as data plane or management plane, does that mean this API is in the data plane? What if There was a problem hiding this comment. I think on the whole we probably should discuss these in-person - would be a lot easier. But answering your questions: Facebook group would be management plane. Planes are somewhat contextual, but you create a facebook group and users post in them.
I don't think APIs have to be categorized as completely data / management. I think this could be done on the operation level. WDYT? I can update the doc.
Yep that's fine, see above. |
||
| The AEPs define the following planes: | ||
|
|
||
| - Management plane: contains AEP-compliant, resource-oriented APIs that | ||
| primarily configure and allow retrieval of resources. APIs in the management | ||
| plane generally do no accept nor interact with user data directly. | ||
| - Data plane: a heterogenous API (ideally resource-oriented) that reads and | ||
| writes user data. Often connects to entities provisioned by the management | ||
| plane plane, such as virtual machines. | ||
|
|
||
| ## Guidance | ||
|
|
||
| ### Management Plane | ||
|
|
||
| Management resources and methods exist primarily to provision, configure, and | ||
| audit the resources that the data plane APIs operates on. | ||
|
|
||
| For example, the following are considered management resources for a cloud | ||
| provider: | ||
|
|
||
| - virtual machines | ||
| - virtual private networks | ||
| - virtual disks | ||
| - a blob store instance | ||
| - a project or account | ||
|
|
||
| ### Data Plane | ||
|
|
||
| Methods on the data plane operate on user data in a variety of data formats, | ||
| and generally interface with a resource provisioned via a management plane API. | ||
| Examples of data plane methods include: | ||
|
|
||
| - writing and reading rows in a table | ||
| - pushing to or pulling from a message queue | ||
| - uploading blobs to or downloading blobs from a blob store instance | ||
|
|
||
| Data plane APIs **may** not comply to AEPs due to requirements including high | ||
| throughput, low latency, or the need to adhere to an existing interface | ||
| specification (e.g. ANSI SQL). | ||
|
|
||
| - For convenience, resources and methods that operate on the data plane **may** | ||
| expose themselves via resource-oriented management APIs. If so, those | ||
| resources and methods **must** adhere to the requirements of the management | ||
| plane as specified in the other AEPs. | ||
|
Comment on lines
+55
to
+56
There was a problem hiding this comment. Which other AEPs do (or will) talk about the requirements of a management plane API for its corresponding data plane APIs? There was a problem hiding this comment. https://google.aip.dev/search?q=plane. Primarily management plane operations have additional requirements around CRUDL. |
||
|
|
||
| ### Major distinctions between management and data plane | ||
|
|
||
| - [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. | ||
| - Are more peformance-sensitive than management planes. | ||
| - Require higher-throughput than management planes. | ||
|
|
||
| [Declarative clients]: ./0003.md#declarative-clients | ||
|
|
||
| ## Changelog | ||
|
|
||
| - **2024-01-27**: initial fork of this AEP from https://google.aip.dev/111. | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,6 @@ | ||
| id: 111 | ||
| state: approved | ||
| slug: planes | ||
| created: 2024-01-27 | ||
| placement: | ||
| category: general |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I added a bunch of comments below, some just proofreading and others more about the content, but my big question is: what guidance does this AEP actually contain? It doesn't seem like there's anything actionable. I don't know what lint rules I'd write, or when I'd refer to it as part of API design. What API design problem is this AEP addressing?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
at Google, there was a large debate about the type of design guidance that would be needed to provide really high-quality declarative APIs (e.g. for Terraform or Kubernetes), at odds with more flexible API needs (generally because of existing precedent, but also sometimes a matter of convenience).
To begin to help address those, we started adding this notion of API planes, and attached various guidance to the management plane in the AIPs: https://google.aip.dev/search?q=management.
to be fair this aligned with some terminology primarily used at Google. Many APIs at least differentiate between a "control plane" and a "data plane": https://docs.aws.amazon.com/whitepapers/latest/aws-fault-isolation-boundaries/control-planes-and-data-planes.html.
I think it's important for us to add some clarity on the various planes of operations and how to differentiate them, given it is common nomenclature for many APIs (especially in the cloud).
I think the content here is actually pretty solid, but it was definitely a work in progress
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That's all useful context...but it doesn't actually answer the question about what actionable guidance is in this AEP. What would a violation of this AEP look like?