Skip to content

Blog

AEP's 2025 Roadmap - Building Momentum

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

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:

  1. An API design specification for gRPC and REST APIs, with a heavy focus on resource-oriented design and standard methods that operate on them.

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

  3. 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:

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

  1. To act as a reference point for organization-agnostic best practices.

  2. 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?

Adopting and sharing resource-oriented API best practices

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

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:

  1. Expanding our linting tools across both Protocol Buffer and OpenAPI specifications
  2. Building more client generators, including Terraform providers and Kubernetes operators
  3. Working with the OpenAPI community on resource-oriented API patterns
  4. 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!