Contents:

• Introduction

• An Alternative to ASPs: API Enhancement Proposals

• From APIOps to API Management as Code

• Interesting Content for this Week

An Alternative to ASPs: API Enhancement Proposals

By Ikenna Nwaiwu

In the last issue, I discussed the API Standard Proposal (ASP), a format I use to help API governance teams discuss API standard change recommendations. I also discussed how it can help promote ownership and structured thinking around API standards. ASPs provide a transparent, collaborative, and community-driven path to evolving an API style guide. I have used ASPs on projects with great success, but I should also mention another proposal format you should consider: AEPs.

An API Enhancement Proposal (AEP) is a design document that provides guidance for API design and development. The AEP format was inspired and adapted from Google's AIP project. An ASP shares some similarities with the Python Enhancement Proposal (PEP) format. Like an ASP, an AEP provides a structured way to propose and discuss changes and improvements. AEP documents have the following structure

1. A title: For example, "Resource Types".

2. Introduction: A brief opening statement that provides background for the AEP but does not provide any instructions. For example, the introductory text for the Error AEP reads: "Effective error communication is an important part of designing simple and intuitive APIs. Services returning standardised error responses enable API clients to construct centralised common error handling logic."

3. Guidance: This section provides the specific API design direction. They can include examples and their explanations. This section can also contain subsections that elaborate further on the details. For example, the Guidance section for “AEP-0122 - Resource paths” (see GitHub entry) has subsections on 'Collection identifiers' and 'Nested collections'.

4. Rationale: An optional section that explains the "why" behind a Guidance. In this section, you can go into detail on design justifications and tradeoffs.

5. History: An optional section that elaborates on significant events and context around edits to the AEP.

6. Further Reading: Bulleted list of other AEPs or external resources.

7. Appendices: Further explanation of the AEP, usually providing alternative options considered.

8. Changelog: Bulleted list of changes, usually described in one line.

AEP documents, published on aep.dev and available in GitHub provide a corpus of API design standards you can base your organisation's standards on. But they also provide a process, that is, a workflow, for discussing, aligning on and adopting standards. In this workflow, new AEPs or revisions to AEPs are raised as pull requests to a Git repo, and they start in the REVIEWING state. From this state, they can be transitioned to WITHDRAWN or APPROVED. You can find the workflow and all the states described here.

Where do AEPs fit on the IDC?

The Ikenna Delivery Canvas (IDC) is a tool I use to map an organisation's API delivery workflow and facilitate discussions on identifying and rooting out inefficiencies and improving API quality. I'll discuss the IDC in full in another post, but for now, you can think of it as a visual representation of the workflow, tools, and practices in your API delivery process.

AEPs fall into two places on Box 5 - API Standards - of my IDC. They provide API style guidelines and a visible API standards update process, as shown in Figure 1 below.

AEPs also fall into Box 4 - API Culture - of my IDC. They help facilitate the work of the API Governance Group and provide a way for the API Community of Practice to contribute to the guidelines. This is shown in Figure 2 below.

Conclusion

The AEP format is another API design document format to consider when creating an API style guide and facilitating API governance conversations. AEPs provide a framework for your API style guide and a workflow for managing improvements to it. Use the AEP or ASP format to enable your API design stakeholders to contribute to API standard improvements.

From APIOps to API Management as Code

Last week, I wrote about how I like the term “API Management as Code“ compared to “APIOps“. You can read my post here.

Interesting Content for this Week

Books

Ryan Day’s Hands-On APIs for AI and Data Science discusses how to design and build APIs that data scientists and AIs love using Python and FastAPI. He also discusses using APIs with GenAI and LLMs.

Articles

Goodbye Linters? How AI is Transforming API Validation:Rafael Granados explores the evolving role of API validation in his article, highlighting the traditional function of linters in ensuring syntactic standards.He points out that AI is driving a shift towards more sophisticated validation, capable of understanding the semantics and intent behind API design.

OpenAI pushes AI agent capabilities with new developer API : According to Benj Edwards the artificial intelligence industry is prioritising the development of autonomous "agents" capable of multi-step task execution. OpenAI has introduced the "Responses API" to facilitate this, enabling the creation of bespoke agents that can interact with company data and navigate websites.

Atsign Introduces Invisible APIs: Enhancing API Security with NoPorts: Atsign has launched Invisible APIs, a new security solution powered by its NoPorts technology, which renders API endpoints undetectable to unauthorised access. This innovation addresses the inherent vulnerabilities of traditional APIs reliant on open ports, which are susceptible to attacks such as denial-of-service and data theft.

The Salesforce API Journey: A Deep Dive: Kristopher Sandoval's piece examines the evolution of Salesforce's API strategy, tracing its development from its early stages to its current prominence.

Building a Model Context Protocol (MCP) server for Discord: This article demonstrates the MCP's practical application by developing a server that connects with the Discord API for message interaction.

5 fundamental strategies for REST API authentication: Priyank Gupta explains that REST APIs, while crucial for modern applications, necessitate strong authentication to protect sensitive data transmitted across systems. Gupta details five traditional and two evolving authentication methods, such as Basic authentication, API keys, OAuth 2.0, and passkeys, highlighting the varying complexity of each.

Is the best API governance strategy a boring one?: The article shares discussions covering the necessity of early governance, its role in managing API complexity, strategies for overcoming resistance to governance, and methods for measuring its return on investment.

Video

APIs Over IPAs 15: Customer Observability with Mike Amundsen: Mike Amundsen and Derric Gilling discuss how API observability is connected to API product management and the API lifecycle. They address how organisations can adapt to evolving observability landscapes, especially with AI advancement.

Conferences

Postman's annual user conference: Step into the future of APIs and AI at POST/CON 25. It’s the ultimate playground for developers, API architects, and tech leaders ready to build smarter, faster, and more secure APIs in the age of generative AI. Date: June 3rd & 4th 2025, Location: JW Marriott Los Angeles L.A. Live, Los Angeles, CA Register Here 

APIdays Helsinki: Theme: “APIs for Innovation, Intelligence, and Impact” Date: June 3rd & 4th 2025. Location: Pikku-Finlandia, Helsinki Register Here

APIdays Germany: Theme: “Accelerate AI Use Cases with APIs” Date: July 2nd & 3rd, 2025. Location: Smartvillage Bogenhausen, München, Germany. Register Here

APIdays London: Theme: “No AI Without APIs” Conference Date: September 22nd - 24th, Location: Convene 155 Bishopsgate, London EC2M 3YD