feat(planes): porting AEP-111 from AIP-111 #85
Conversation
No major changes, besides removing refrerences to AIPs.
toumorokoshi
force-pushed
the
push-uoxyqrrkwrsr
branch
from
4721e8c to
2670a2e
Compare
aep/general/0111/aep.md
Outdated
| - pushing to or pulling from a message queue | ||
| - uploading blobs to or downloading blobs from a blob store instance | ||
|
|
||
| Data plane APIs **may** be heterogenous across a larger API surface, due to |
There was a problem hiding this comment.
What does it mean for an API to be heterogenous? Not entirely resource-oriented?
What is a "larger API surface"? Larger than what?
There was a problem hiding this comment.
across a larger API surface doesn't seem helpful here - will remove.
I probably can be more precise that heterogeneity - I mean that there's more leeway in the requirements of data plane vs those for management APIs, up to being completely non-AEP compliant (e.g. SQL or a protocol for blob storage).
| resources and methods **must** adhere to the requirements of the management | ||
| plane as specified in the other AEPs. |
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.
| @@ -0,0 +1,66 @@ | |||
| # Planes | |||
There was a problem hiding this comment.
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.
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.
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?
toumorokoshi
force-pushed
the
push-uoxyqrrkwrsr
branch
from
f8b2f31 to
4bde4b2
Compare
No major changes, besides removing refrerences to AIPs.