From 323dd409ea21166fff606ba2ef914355e6767fcd Mon Sep 17 00:00:00 2001 From: Yusuke Tsutsumi Date: Thu, 19 Dec 2024 22:21:39 -0800 Subject: [PATCH] blog: update 2024-in-review some additional fit and finish: - links in the headers look kind of weird, so moving them into the content. - removing unneeded ** which would further bold headers which are already bold. --- src/content/docs/blog/2024-in-review.md | 37 +++++++++++++------------ 1 file changed, 19 insertions(+), 18 deletions(-) diff --git a/src/content/docs/blog/2024-in-review.md b/src/content/docs/blog/2024-in-review.md index d14815a..cdbabb5 100644 --- a/src/content/docs/blog/2024-in-review.md +++ b/src/content/docs/blog/2024-in-review.md @@ -6,7 +6,7 @@ authors: - name: Alex Stephen - name: Yusuke Tsutsumi --- -# **Building Better APIs Together: 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. @@ -17,27 +17,28 @@ A brief summary of the achievements outlined below are: - 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** + +## 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** +## Major Technical Achievements -### **The AEP Compiler ([aepc](https://github.com/aep-dev/aepc))** +### 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. +We introduced [aepc](https://github.com/aep-dev/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**](https://github.com/aep-dev/aepcli) **0.1: A Command-Line Interface for Everyone** +### aepcli: A Command-Line Interface for Everyone -The launch of [aepcli](https://github.com/aep-dev/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. +The launch of version 0.1 of [aepcli](https://github.com/aep-dev/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. -### [**The AEP **Explorer**](https://github.com/aep-dev/aep-explorer)** +### aep-explorer -To complement our command-line tools, we developed a web-based UI for browsing and interacting with AEP-compliant APIs. This provides a more visual way to understand and experiment with APIs while maintaining the same consistent interaction patterns that make AEPs valuable. +To complement our command-line tools, we developed a web-based UI for browsing and interacting with AEP-compliant APIs: [aep-explorer](https://github.com/aep-dev/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** +### 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](https://github.com/aep-dev/aep-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. @@ -47,7 +48,7 @@ The linter's approach balances pragmatism with standards enforcement \- while so 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** +### Improved Infrastructure A major focus this year was improving the components used for learning about the AEP standards and enforcing them in our organization. @@ -55,21 +56,21 @@ To help teams get started, we've built comprehensive test cases and example APIs 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** +## Community Growth -### **The March Barn Raising** +### 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** +### 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** +### Educational Content We launched the [@aepdev](https://www.youtube.com/@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** +## Looking Forward to 2025 As we enter the new year, our focus areas include: @@ -78,7 +79,7 @@ As we enter the new year, our focus areas include: 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** +## Get Involved We're building AEPs in the open and welcome contributions of all kinds. You can join us: @@ -87,4 +88,4 @@ We're building AEPs in the open and welcome contributions of all kinds. You can * On GitHub at [github.com/aep-dev](https://github.com/aep-dev) * Through our documentation at [aep.dev](https://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\! \ No newline at end of file +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\!