feat(planes): porting AEP-111 from AIP-111

[toumorokoshi]

No major changes, besides removing refrerences to AIPs.

[rofrankel]

What does it mean for an API to be heterogenous? Not entirely resource-oriented?

What is a "larger API surface"? Larger than what?

[toumorokoshi]

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).

[rofrankel]

Which other AEPs do (or will) talk about the requirements of a management plane API for its corresponding data plane APIs?

[toumorokoshi]

https://google.aip.dev/search?q=plane. Primarily management plane operations have additional requirements around CRUDL.

[rofrankel]

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?

[toumorokoshi]

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

[rofrankel]

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?

[mkistler]

Looks good. 👍