Marsh Gardiner

3 posts by Marsh Gardiner

Announcing the aep-2026 Release

Dec 8, 2025

Marsh Gardiner

Yusuke Tsutsumi

Alex Stephen

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

Mar 31, 2025

Alex Stephen

Marsh Gardiner

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

Feb 7, 2025

Mak Ahmad

Yusuke Tsutsumi

Marsh Gardiner

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