3 ms·

AEPs: API Enhancement Proposals

20 points by nateb2022 5mo ago

cbarrick 5mo ago
This is a fork of Google's AIPs (API Improvement Proposals) [1], which is the standard for all of Google's public APIs. More context at [2]. [1]: https://aip.dev https://aip.dev [2]: https://aep.dev/blog/history-of-aeps/ https://aep.dev/blog/history-of-aeps/
- ventana 5mo ago
  > which is the standard for all of Google's public APIs Far from that, unfortunately. A lot of Google public APIs predate AIPs and it's practically impossible to fix them and make them compliant. Possibly the worst offender is the Compute Engine API [1], which, to the best of my knowledge, is REST only (no gRPC), uses its own conventions related to page size / next page token, and, in general, is special in many ways. One of the ways it's special is its size: its definition in Google's own Discovery format [2] is a 6MB JSON. It's an extremely difficult problem to standardize multiple APIs produced by multiple teams, and then keep the new changes compliant. Google did a great job, but it's still very far from the perfect state. [1]: https://docs.cloud.google.com/compute/docs/reference/rest/v1 https://docs.cloud.google.com/compute/docs/reference/rest/v1 [2]: https://www.googleapis.com/discovery/v1/apis/compute/v1/rest https://www.googleapis.com/discovery/v1/apis/compute/v1/rest - warning: 6 megabytes JSON [edit: typo]
  - cbarrick 5mo ago
    I say it's the "standard" because all new public APIs must conform to the latest AIPs. But yes, Google has plenty of legacy APIs. And yes, GCE in particular is a HUGE pain.
agentik 5mo ago
https://news.ycombinator.com/item?id=48126889 https://news.ycombinator.com/item?id=48126889 just posted a thread, for a compeletly unrelated AIP definition :)
endtime 5mo ago
I worked on this for a couple years (have been much less active lately), surprised to see it on the front page of HN but happy to answer questions about it.
thegagne 5mo ago
Happy adopter of AEP here. It has been super helpful and the ecosystem is growing around it. The real benefit is having a standardized pattern for APIs, with automation and predictability built in. Not everything can be modeled as a resource, but for any API that fits that, it’s fantastic. It’s a bit restrictive at times, but those restrictions often shed light on bad architecture/data modeling. They worked through a lot of feedback last year and cut a 2026 LTS release to give strong confidence to start building tooling around it. Check out https://aepbase.io/ https://aepbase.io/ for an example and fun way to get started.

20 points by nateb2022 5mo ago

This is a fork of Google's AIPs (API Improvement Proposals) [1], which is the standard for all of Google's public APIs. More context at [2]. [1]: https://aip.dev https://aip.dev [2]: https://aep.dev/blog/history-of-aeps/ https://aep.dev/blog/history-of-aeps/

ventana 5mo ago
> which is the standard for all of Google's public APIs Far from that, unfortunately. A lot of Google public APIs predate AIPs and it's practically impossible to fix them and make them compliant. Possibly the worst offender is the Compute Engine API [1], which, to the best of my knowledge, is REST only (no gRPC), uses its own conventions related to page size / next page token, and, in general, is special in many ways. One of the ways it's special is its size: its definition in Google's own Discovery format [2] is a 6MB JSON. It's an extremely difficult problem to standardize multiple APIs produced by multiple teams, and then keep the new changes compliant. Google did a great job, but it's still very far from the perfect state. [1]: https://docs.cloud.google.com/compute/docs/reference/rest/v1 https://docs.cloud.google.com/compute/docs/reference/rest/v1 [2]: https://www.googleapis.com/discovery/v1/apis/compute/v1/rest https://www.googleapis.com/discovery/v1/apis/compute/v1/rest - warning: 6 megabytes JSON [edit: typo]
- cbarrick 5mo ago
  I say it's the "standard" because all new public APIs must conform to the latest AIPs. But yes, Google has plenty of legacy APIs. And yes, GCE in particular is a HUGE pain.

agentik 5mo ago

https://news.ycombinator.com/item?id=48126889 https://news.ycombinator.com/item?id=48126889 just posted a thread, for a compeletly unrelated AIP definition :)

endtime 5mo ago

I worked on this for a couple years (have been much less active lately), surprised to see it on the front page of HN but happy to answer questions about it.

thegagne 5mo ago

Happy adopter of AEP here. It has been super helpful and the ecosystem is growing around it. The real benefit is having a standardized pattern for APIs, with automation and predictability built in. Not everything can be modeled as a resource, but for any API that fits that, it’s fantastic. It’s a bit restrictive at times, but those restrictions often shed light on bad architecture/data modeling. They worked through a lot of feedback last year and cut a 2026 LTS release to give strong confidence to start building tooling around it. Check out https://aepbase.io/ https://aepbase.io/ for an example and fun way to get started.