AEP | Blog

Announcing the aep-2026 Release

Mon, 08 Dec 2025 00:00:00 GMT

The Coordination Challenge

Building software is a team sport, but keeping everyone on the same page is hard. When every team has to invent their own API patterns — deciding how pagination works, or how to format errors — we end up with a lot of wasted effort and systems that don’t quite fit together. This isn’t just about having “standards”. It’s about ensuring that users and tools don’t have to continuously relearn the same standards.

A Shared Standard and Tools

The aep-2026 edition is our answer to that friction. It is an opinionated API design specification, providing well-defined requirements around common REST concepts like CRUD standard methods, pagination, filtering, and more. By agreeing on these common patterns, we make it easier for services to talk to each other, clients to be built, and for developers to move between projects without needing to learn idiosyncratic conventions.

AEP (API Enhancement Proposals) is an open-source, “anti-bike shedding” kit. It answers the routine questions so we can all focus on the interesting ones. It’s about a shared foundation that lifts everyone up and lets everyone build on the same tooling platform.

Stability for Builders

To build lasting tools, you need a solid foundation. You can’t build tooling on top of a spec that changes regularly. The aep-2026 edition is a major milestone because we are introducing a stable version of the specification and establishing a release cadence with AEP-300. This decouples stability for consumers and evolving our best practices:

For Builders: Invest in linters, libraries, and other tools today knowing they will keep working for years.
For the Future: We can keep discussing new improvements for the next edition (AEP-2028) without breaking the tools you rely on right now.

The tooling is guaranteed to be compatible for the three most recent editions of AEPs, effectively a 6 year stability cycle based on our current 2-year cadence.

The Tooling Ecosystem

Because the standard is now stable, we can share a set of tools that help everyone do less grunt work. The 2026 edition launches with a compatible ecosystem ready for you to use:

Infrastructure: A Terraform Provider to handle the deployment details.
Integration: An MCP Server to let AI agents understand your APIs out of the box.
Exploration: An Interactive Web UI to make daily development smoother.
Speed: A CLI to quickly call an AEP-compatible service.

Next Steps

Come see what we’ve built. Whether you use the whole platform or just grab a few good ideas, you are welcome here.

Explore: Check out the Tools Page to see what’s available or visit the aep.dev site to review the numbered rules.
Join: Drop into a weekly Friday meeting or hop into our #aep Slack channel in the CNCF Slack to ask questions or say hello.

Contributors

This release is the result of years of work and feedback from the community. Special thanks to Richard Frankel, Marsh Gardiner, Yusuke Tsutsumi, Alex Stephen, and Mike Kistler for their stewardship as maintainers on this release. We are also grateful to the growing community of contributors, including David Gagne, Olivier Cano, Oscar Söderlund, and others!

AEP Terraform Provider

Mon, 31 Mar 2025 00:00:00 GMT

A core thesis of the AEP project has been that API design constraints can facilitate the creation (and maintenance!) of API client tools. In many companies, teams are staffed to build out CLI tools, Terraform providers, UIs, LLM agents, and various other tools that act as thin layers on top of a company’s APIs. The AEP project aims to ensure that these tools can be easily generated on top of our API design, ensuring that companies can move faster with less overall effort. We’re excited to launch our first version of a fully auto-generated Terraform provider based off the AEPs.

What is Terraform?

Terraform is a powerful Infrastructure-as-Code (IaC) tool that allows you to define and manage your infrastructure using code. Infrastructure-as-Code, in general, is the practice of managing and provisioning infrastructure through machine-readable definition files rather than through manual processes. This means you can automate the creation, modification, and deletion of resources across various cloud providers and on-premises environments, ensuring consistency, repeatability, and version control.

Cloud companies often build out Terraform providers, which are responsible for establishing differences between the cloud and the user’s intent, determining which API requests are necessary, making those requests, and handling any follow-up actions.

How do the AEPs help with this?

Most companies must staff engineers just to maintain their Terraform provider. However, making AEP-compliant APIs can give you providers for no additional effort beyond writing the API! Let’s take a look at a pseudocode version of the Terraform lifecycle.

userIntention := GetTerraformPlan()
currentState := ReadResource(userIntention)

if currentState != null:
  if user wishes to delete:
     DeleteResource(currentState)
  else if currentState != userIntention:
     UpdateResource(userIntention)
else:
  CreateResource(userIntention)

Two different sets of problems emerge and the AEPs are well-suited for solving both of them.

The first set of problems revolves around the grouping and calling of APIs. There’s a variety of tools in the market that will call an API method given a set of parameters and an OpenAPI description (or even just a URL). Terraform doesn’t expose individual API methods, but instead exposes a resource schema. This raises a variety of questions when developing a Terraform provider:

What are my resources?
How do I know which API methods to call for a given resource?
Is there a single API method that can be called for each CRUD operation, or will I need to chain together API calls to achieve my result?
How do I derive my resource schema from four distinct CRUD APIs? Is it simply the union of all the body parameters from the four CRUD API methods?

AEP APIs are resource-oriented by default, so just following the AEPs can address all of the problems above. The Terraform provider can “know” which API methods should be called and how they relate to each other.

What about API responses?

The second set of problems comes from reading API responses. In the pseudocode above, the Read response needs to be parsed and checked against the Terraform plan. This means that the Terraform provider needs to understand the relationship between the API response (beyond simple error checking) and the user’s intention. More questions emerge:

Does the response of the Read API match the resource schema? What changes need to be made to match the Read API response to the potential resource schema?
Are there multiple ways that the server will accept a single value? If so, how can I be sure that two semantically equivalent values do not result in a diff against the Terraform plan?
If a boolean value does not appear in the JSON response, does that mean it’s false? (And likewise for numeric values being 0, string values being the empty string, and so on.)

Many of these questions come down to the preference of the API developer. In fact, some of them cannot be defined by an API schema! The AEPs encode these differences in our specification, so that tools like our Terraform provider can make assumptions about how to parse the responses of our APIs.

The AEP Terraform Provider

The AEP Terraform provider solves these problems. The provider is a template that can be pointed to any OpenAPI spec that features APIs complying with the AEPs. Since the APIs are resource-oriented and AEP-compliant, the provider is able to create a resource schema at runtime that perfectly matches the APIs. Did your team build a new feature? Just update your OpenAPI spec and the provider will add it without users having to update their providers.

Users are able to send over arbitrary headers so that the provider will work with any authentication solution you may have.

When users run terraform apply, the provider automatically knows how to create Create, Read, Update, and Delete requests, handle authentication, and return errors. More crucially, it understands how to handle the responses from those requests. The provider understands what values to expect from the Get requests and the proper way to handle difference checking against the user’s intention.

What comes next?

While the Terraform provider lifecycle appears simple at first glance, the details contain a deceptive amount of detail. This is detail that can only be learned through trial-and-error, which is difficult when APIs are often only designed once.

By building out the Terraform provider, we’re even more convinced than ever that the AEP specification can prove the thesis that client tooling can be more easily built on top of consistent APIs.

AEP's 2025 Roadmap - Building Momentum

Fri, 07 Feb 2025 00:00:00 GMT

As we begin 2025, we want to share our ambitions for the API Enhancement Proposals (AEP) project. After a successful 2024 that saw the launch of several key tools and growing community engagement, our focus for 2025 is on stabilizing the specification while expanding the ecosystem of tools.

Specification and Standards

A major milestone for 2025 will be the v0.1 release of the AEP specification. This represents the culmination of much work to adapt and expand the original API Improvement Proposals, with particular focus on resource-oriented design patterns that work across both Protocol Buffers and HTTP APIs. The 0.1 release will include support for the standard methods, long-running operations (LRO), and other design patterns supported across our toolchain.

Tooling Releases

Building on the specification, we will be releasing initial versions of core tools in 2025:

A production-ready version of the OpenAPI linter with coverage of the standard methods, list-related patterns, and LROs of the 0.1 specification
An enhanced Protocol Buffer linter reflecting the latest AEP guidance
aepcli with LRO support of the 0.1 specification
The first official release of our Terraform provider
A stable release of aep-explorer for visually navigating AEP-compliant APIs

Community Growth

In May, we plan on giving a talk about aep.dev at API Days New York. The video will be released online for those who would like to view but cannot attend.

Building on the success of our 2024 barn raising, we are planning another community event after the 0.1 specification release. This will focus on helping organizations learn about the specification, enabling adoption of our specification and tools, and onboarding interested contributors to the project.

Longer-Term Goals

In the second half of 2025, we’ll focus on:

Stabilizing and potentially releasing version 0.1 of aepc, our toolkit for generating service stubs from resource definitions
Expanding existing tooling based on real-world usage and feedback
Expanding and refining guidance

Whether you are building new APIs or working to improve existing ones, 2025 will be an exciting year to get involved with AEPs! Join us in our mission to make APIs more consistent and maintainable across many industries.

Get Involved

Join us:

On CNCF Slack in the #aep channel
At our weekly community meetings (Fridays at 11:30am PT)
Through our documentation at aep.dev
On GitHub at github.com/aep-dev

The History and Philosophy of AEPs

Mon, 03 Feb 2025 00:00:00 GMT

The History and Philosophy of AEPs

There have been a lot of interest in the AEPs, and a question that often comes up is “where did the AEPs come from?” and “what are the underlying motivation and philosophies of the project?“. This blog post aims to help answer those questions.

What are AEPs?

AEP is short for “API Enhancement Proposal”, intended to be a comprehensive specification, set of best practices, and tools to help an organization provide best-in-class resource-oriented APIs.

More specifically, the following is provided:

An API design specification for gRPC and REST APIs, with a heavy focus on resource-oriented design and standard methods that operate on them.
Design patterns for common use cases such as long-running operations, resource revisions, filtering, with best practices aggregated from API design experts with experience at Google, Microsoft, Meta, Roblox, and DataBricks.
An ecosystem of server-side and client-side tooling to produce and consume AEP-compliant APIs.

How did the AEPs begin?

The history of AEPs begin with the AIPs: Google API Improvement Proposals: a set of design patterns for resource-oriented APIs, focusing primarily on protobuf. AIPs themselves were then open sourcing of internal documentation around Google API’s best practices.

Along with Google’s own design practices, aip.dev also had a generic industry wide component, that primarily focused on the idea of creating design style guides that tailor to an organization’s own needs. This project includes components such as a style guide site generator as well as a template of more generic guidance.

Although aip.dev is not a formal API specification, an ecosystem of tooling does exist that adheres to it, including:

A protobuf based api-linter.
A client library generator.

Among the contributors to aip.dev, some wanted to see a stronger formalization of the API design guidance itself, for a few reasons:

To act as a reference point for organization-agnostic best practices.
To enable an official ecosystem of tooling to make best-practice APIs easier to build and consume.

This group forked aip.dev and created aep.dev. Since its founding in 2023, aep.dev has rapidly progressed in building out a tooling ecosystem, and proving that well-designed APIs can truly enable a simple-to-maintain but powerful ecosystem of tooling (read more here).

What philosophies drive aep.dev?

We do not want to reinvent the wheel. Instead, our guidance is based on IETF RFCs that exist around HTTP semantics, using them when applicable.

Powerful server-side and client-side tooling, enabled by simple, consistent APIs.

As organizations develop their APIs, organizations must often create their own service generators to create consistency, as well as create client-side tooling to consume them. This includes:

Linters and style guide checkers to ensure API consistency
server-side generators, handling the creation of boilerplate interfaces that enable common features that include: CRUD of basic resources, pagination and filtering for lists, precondition checking, and documentation generation.
Clients that interface with these APIs, including: SDKs, command line interface, web-based UIs, asset inventories.

Rather than have every organization create their own clients, AEPs strive to provide the above tools, allowing an organization to focus on their goal and from having to have full teams dedicated to maintaining these tools.

Where to learn more?

Now that you have an understanding of the aeps, we encourage you to explore the project, use the specification to help guide your APIs, and use the tooling to help produce and consume them. Visit the home page for more information!

AEP's 2024 Year in Review

Thu, 19 Dec 2024 00:00:00 GMT

Building Better APIs Together: AEP’s 2024 Year in Review

As we close out 2024, we want to share the significant strides the API Enhancement Proposals (AEP) project has made in creating a more cohesive API ecosystem. What started as a fork of Google’s API Improvement Proposals has evolved into something much more ambitious: an open, community-driven standard for building resource-oriented APIs that work consistently across different protocols and platforms.

A brief summary of the achievements outlined below are:

The creation of aepc, an AEP “compiler” that takes a succinct resource definition and generates protobuf and OpenAPI schemas.
The 0.1 release of aepcli, which can consume aep-compliant APIs and generate a resource-oriented command-line-interfaces dynamically.
A complete linter for protobuf APIs, and starting an OAS variant.
aep-explorer: a prototype of a WEB UI to explore aep-compliant APIs.
A redesigned website (aep.dev), where this blog post is published!

The Vision Takes Shape

This year clarified our core belief that API design shouldn’t be a bikeshedding honeypot. By collecting hard-won design patterns from across the industry, we’ve worked to narrow the decisions API producers need to make while improving the experience for API consumers. Our approach focuses on resource-oriented design principles that can be expressed in both Protocol Buffers and OpenAPI, making AEPs protocol-agnostic while maintaining strong opinions about what makes APIs more usable and maintainable.

Major Technical Achievements

aepc: The AEP compiler

We introduced aepc, our service compiler that transforms concise resource definitions into fully-specified APIs. With just a few dozen lines of YAML describing your resources and their relationships, aepc generates complete Protocol Buffer and OpenAPI specifications that adhere to AEP standards. This dramatically reduces the boilerplate needed to create consistent APIs while enforcing best practices through generation rather than just validation.

aepc is just a prototype with no official release at this moment, but it has been very useful, producing AEP-compliant OpenAPI and protobuf specifications that are used as examples in the specification.

aepcli: A Command-Line Interface for Everyone

The launch of version 0.1 of aepcli marked a significant milestone in our tooling journey. Rather than requiring every API provider to build their own CLI, aepcli dynamically generates a powerful command-line interface from any AEP-compliant API’s OpenAPI specification. This client-side approach means new API features are immediately available without requiring CLI updates, solving a common pain point in API tooling.

aep-explorer

To complement our command-line tools, we developed a web-based UI for browsing and interacting with AEP-compliant APIs: aep-explorer . This provides a more visual way to understand and experiment with APIs while maintaining the same consistent interaction patterns that make AEPs valuable.

Enhanced Linting Capabilities

A major focus this year was improving our linting capabilities, particularly for OpenAPI specifications. Mike Kistler led the effort to revitalize our OpenAPI linter, implementing rules for key AEPs including AEP-132 (List methods) and AEP-135. The linter helps teams validate their APIs against AEP guidance, catching common issues early in the development process.

Significantly progress was also made for our protobuf linter, which is now compliant with all of the updated guidance in aep.dev.

The linter’s approach balances pragmatism with standards enforcement - while some rules are mandatory, others can be selectively adopted based on an organization’s needs. This flexibility helps teams gradually adopt AEP practices while maintaining consistent APIs. The project uses Spectral as its foundation, allowing teams to build on an established tooling ecosystem while adding AEP-specific validations.

To help teams get started, we’ve included comprehensive test cases and example APIs that demonstrate proper implementation of AEP patterns. The linter has already helped identify areas where our documentation needed clarification, particularly around operation IDs and resource naming conventions.

Improved Infrastructure

A major focus this year was improving the components used for learning about the AEP standards and enforcing them in our organization.

To help teams get started, we’ve built comprehensive test cases and example APIs that demonstrate proper implementation of AEP patterns. The linters have already helped identify areas where our documentation needed clarification, particularly around operation IDs and resource naming conventions.

Additionally, we’ve built out a new aep.dev website based on a new framework to help highlight our guidance and to help the team release new content over time.

Community Growth

The March Barn Raising

On Pi Day (March 14), we held our first community “barn raising” event, bringing together contributors from across companies and time zones. The event focused on improving documentation, adding OpenAPI examples, and making AEPs more accessible to newcomers. This collaborative effort helped us identify and address gaps in our guidance while strengthening our community bonds.

Expanding Global Reach

Recognizing our growing international community, we established EU-friendly meeting times and welcomed contributors from companies like DoubleVerify, providing valuable feedback on real-world AEP adoption. This led to improvements in our documentation and examples, particularly around pagination and custom methods.

Educational Content

We launched the @aepdev YouTube channel featuring detailed demonstrations of our tooling and explanations of AEP concepts. These videos help newcomers understand both the technical details and the broader vision of what we’re building.

Looking Forward to 2025

As we enter the new year, our focus areas include:

Expanding our linting tools across both Protocol Buffer and OpenAPI specifications
Building more client generators, including Terraform providers and Kubernetes operators
Working with the OpenAPI community on resource-oriented API patterns
Supporting more companies in adopting AEPs, with clear migration paths and tooling support

Get Involved

We’re building AEPs in the open and welcome contributions of all kinds. You can join us:

On CNCF Slack in the #aep channel
At our weekly community meetings (Fridays at 11:30am PT)
On GitHub at github.com/aep-dev
Through our documentation at aep.dev

Whether you’re building new APIs or working to improve existing ones, we believe AEPs can help make that process more consistent and maintainable. Join us in building better APIs together!

AEP | Blog

Announcing the aep-2026 Release

The Coordination Challenge

A Shared Standard and Tools

Stability for Builders

The Tooling Ecosystem

Next Steps

Contributors

AEP Terraform Provider

What is Terraform?

How do the AEPs help with this?

What about API responses?

The AEP Terraform Provider

What comes next?

AEP's 2025 Roadmap - Building Momentum

Specification and Standards

Tooling Releases

Community Growth

Longer-Term Goals

Get Involved

The History and Philosophy of AEPs

The History and Philosophy of AEPs

What are AEPs?

How did the AEPs begin?

What philosophies drive aep.dev?

Adopting and sharing resource-oriented API best practices

Powerful server-side and client-side tooling, enabled by simple, consistent APIs.

Where to learn more?

AEP's 2024 Year in Review

Building Better APIs Together: AEP’s 2024 Year in Review

The Vision Takes Shape

Major Technical Achievements

aepc: The AEP compiler

aepcli: A Command-Line Interface for Everyone

aep-explorer

Enhanced Linting Capabilities

Improved Infrastructure

Community Growth

The March Barn Raising

Expanding Global Reach

Educational Content

Looking Forward to 2025

Get Involved