Compatibility/incompatibilities with AIP.dev?

[akavel-reply]

I have a working knowledge of AIP.dev, and just today I discovered AEP.dev. I see AEPs are officially inspired/forked from AIPs; but I'm super confused about the practicalities. My initial questions include most notably:

1. Will AIP tools work with AEPs, or will they not? At a quick glance, it seems to me AIPs have more tools/bigger ecosystem, with longer maturity (or am I mistaken?). As such, I'd love to be able to use the AIPs tools ecosystem regardless if I try to follow AEPs or AIPs. Is that possible? Or is it not? or nobody knows/cares?
2. Again, from a quick glance, looking at the website, the list of AEPs seems much shorter than that of AIPs (or am I missing something?). Also, I'm just more familiar with AIPs for the time being. On the other hand, fellow developers might be more open to a more generic/universal set of standards (thus AEPs) than ostensibly Google-specific ones (AIPs). I'd love to sell them on AEPs, but I'm myself not really sold on them yet. Can you help me understand the seemingly much smaller surface of AEPs vs. AIPs, plus also whether it's possible for example to start with AIPs, but safely assume that we could eventually gradually migrate to AEPs? or, alternatively, to try and start with AEPs but supplement them with AIPs where they're missing? (The latter is a tougher call, as it would require knowledge of two extensive, nuanced, and similar-yet-subtly-different sets of standards documents.)

[toumorokoshi]

Hi there! confusion with aip.dev is a common point.

 Will AIP tools work with AEPs, or will they not? At a quick glance, it seems to me AIPs have more tools/bigger ecosystem, with longer maturity (or am I mistaken?). As such, I'd love to be able to use the AIPs tools ecosystem regardless if I try to follow AEPs or AIPs. Is that possible? Or is it not? or nobody knows/cares?

AIP tools

Can you clarify what you mean by "AIP tools"? The main one I am aware of is the AIP linter (https://linter.aip.dev/), although there are other parts of the ecosystem, such as the google.api.http annotations, that are mentioned in the AIPs (as well as AEP) and have support in tools like grpc-gateway and envoy-proxy.

There are other tools that interoperate, like the gapic generators (https://github.com/googleapis/gapic-generator), which primarily serve the interests of Google. Some companies, such as Roblox, have forked them, but there is no publicly consumable repository I'm aware of.

I was the maintainer of aip.dev throughout 2020, so things may have changed since then, but this was my understanding of the OSS ecosystem.

AEP tools and ecosystem

In contrast to the aip tools, the AEPs provide the following:

• A terraform provider (there is no AIP equivalent)
• A command line tool (no AIP equivalent)
• OpenAPI validator (no AIP equivalent)
• UI Explorer (no AIP equivalent)
• MCP server generator (no AIP equivalent).
• https://github.com/aep-dev/api-linter (AIPs api-linter)

[toumorokoshi]

Again, from a quick glance, looking at the website, the list of AEPs seems much shorter than that of AIPs (or am I missing something?). Also, I'm just more familiar with AIPs for the time being. On the other hand, fellow developers might be more open to a more generic/universal set of standards (thus AEPs) than ostensibly Google-specific ones (AIPs). I'd love to sell them on AEPs, but I'm myself not really sold on them yet. Can you help me understand the seemingly much smaller surface of AEPs vs. AIPs, plus also whether it's possible for example to start with AIPs, but safely assume that we could eventually gradually migrate to AEPs? or, alternatively, to try and start with AEPs but supplement them with AIPs where they're missing? (The latter is a tougher call, as it would require knowledge of two extensive, nuanced, and similar-yet-subtly-different sets of standards documents.)

For the AEPs, we purposefully only ported those that we felt were critical for an API specification. There are some more nuanced AIP best practices that we considered important (beta-blocking changes, stability levels, etc) that we did not prioritize.

What the AEPs have that AIPs don't:

• OpenAPI / HTTP + JSON examples and recommendations.
• some fundamental changes on the protobuf side like naming "path" instead of "name", error response objects, an apply method.

I don't think using the number of AIPs vs AEPs would be a good way to understand the relative depth and value of the guidance - there are several AEPs that we have clarified an extended beyond what the AIPs have (generic fields, adding apply methods, clarification on edge cases around (see aep-2026 (view) for a few). I'd propose looking at individual proposals / pages to make that evaluation.

AIP-AEP compatiblity

A lot AIP-based APIs, when exposed through a gRPC-http proxy using the google.api.http annotations, will probably work out of the box with AEP tooling without any changes. However, if you're building a new API and intend to leverage the tooling, I'd strongly recommend starting with the AEP guidance: many parts are similar, and the AEP tools have guaranteed compatibility with them.

or, alternatively, to try and start with AEPs but supplement them with AIPs where they're missing? (The latter is a tougher call, as it would require knowledge of two extensive, nuanced, and similar-yet-subtly-different sets of standards documents.)

If there's a specific AIP you're missing, you could either raise that as an issue / slack message and we'll be happy to look at adding it! Or feel free to send a PR yourself. I'd suggest that over supplementing with AIPs, primarily to avoid any possible compatibility issues.