Contents:

• Introduction

• Using ASPs to Improve Your API Governance Meetings

• Interesting Content for this Week

• Upcoming Conferences

Introduction

Hello! Many companies spend way too much time debating API standards in their API governance meetings. In this issue, I explain a way to reduce your lead time for API standard changes. Enjoy!

Using ASPs to Improve Your API Governance Meetings

by Ikenna Nwaiwu

Problem

Your API style guide needs to be updated, and your API governance team meets weekly to discuss and make changes. At last week’s call, you asked a team member to research API pagination options and come to this week’s call with recommendations so the team can review and decide. They have done the research. But lo and behold, they can’t make it to this week’s call due to unavoidable circumstances. However, they promise to turn up at next week’s call. What do you do? Sure, you can wait till next week, but that would be a lead time of at least two weeks before you make the updates. 

Solution

Rather than always wait to make API standard discussions in in-person meetings, I suggest you use what I call API standard proposals (ASPs). An ASP is a written API style guide or API delivery process change recommendation that an API governance team or API community of practice can peer review and approve. It contains a definition of the problem, options considered, and proposed changes. Inspired by RFCs, ADRs, and Google AIPs,  it typically has the following sections, but use your judgement to decide which you need: 

1. Title and author

2. Status of the document: Draft, Proposed, Under Review, Approved, or Rejected.

3. Context and Problem Statement 

4. Use cases the proposal will impact

5. List of Considered Options 

6. For each option

   • Example / prior art 

   • Pros and Cons 

7. Proposed option

8. Automation to enforce the proposed option (if applicable)

9. What tooling can we use to enforce in the CI/CD pipeline or the IDE? (For example, linting rules).

10. Approval table, showing approver, decision (Approved, Rejected or Needs Work) and date. 

11. Links to external resources and standards for further reading. 

12. Change log

After writing an ASP, the proposer can submit it to the API governance team, but ideally to the API community of practice (COP, also called an API guild), where everyone interested can review it and provide comments or suggest changes to the proposal. Even though every interested person can provide feedback, it is the responsibility of the named governance team members on the approval table to sign off the document by providing a decision on it - Approved, Rejected or Needs Work. If the proposal is accepted, the API style guide can be updated to reflect the change. 

You can adapt the ASP document structure and process I describe above to your context. Here are a few tips to guide you:

• You can provide an ASP as a template that users can fill out. This can be via Google Docs, Confluence, or as markdown in a Git collaboration repo - my favourite option because of the excellent version control you get. Whichever option you provide, it is essential that reviewers can make comments. 

• The structure of the ASP is a guide, but use your judgement on which sections are mandatory for your context. Provide a lightweight example to help proposers. 

• A member of your governance team can be responsible for facilitating or ‘shepherding’ ASPs, ensuring the critical sections are filled out and that it is in an adequate state for review. Note that in the ASP structure I provide, I have not marked which areas are mandatory. I will leave that to the ASP facilitator to specify as they adapt the template to their context. 

• Your ASP template should make clear who or where to submit the ASP to (is it a pull request, or do you have to send the link of the page to somone or post on a Slack channel?). Also, it should give the submitter an indication of how long it will take before they get a review of their ASP, so they don’t have to continually chase.  

Measure of Success

There are two performance metrics the ASP aims to improve. They are 

• Standards change lead time: The time it takes to propose and change the organisation’s API style guide. 

• API standards satisfaction: How satisfied are developers with the quality of API standards (that is, their comprehensiveness and clarity?)  

Before introducing ASPs, it is worth doing a quick survey in your API COP, to get a feel of how your community rates your governance process along these lines. 

Benefits of ASPs

• Ownership and engagement: When the API development team use ASPs to propose changes to API standards, it gives them a sense of ownership over the standards. The responsibility of reviewing the ASPs and providing their approval also keeps every member of the governance team engaged. This is a good way of getting every member of the governance team engaged in the process. 

• Structured thinking: It’s a way to help proposers and the governance team to carefully think through proposed changes 

• Visibility and collaboration: It documents and standardises a process for anyone to submit proposals for API style guide updates. This visibility promotes collaboration on API standards. Visibility and collaboration also improve API standards satisfaction by ensuring developer input is consistently heard.

• Reduced load on the governance team: While the API governance team should take the lead in ensuring the right API standards are in place, the ASP process means it is not only up to them.  They can focus more on reviewing proposals others raise.

Contraindications

• An ASP makes sense at scale and is meant to create alignment on standards with all stakeholders. This is why Google put in the AIP process. If your organisation is small and you are only dealing with a few teams and can discuss standards quickly, you don’t need this. But if you have more than three teams or 50 developers, you may want to consider ASPs.

Assumption

One assumption in using ASPs is that there is a quality gate in your API design process - perhaps an API review or automated check, that checks to see standards are followed. Without such a gate, there is no motivation to want to propose a change since violations of existing standards will be allowed anyway. 

Share your experience

Have you had success with a process similar to the ASP I describe? Get in touch and share your experience.

Interesting Content for this Week

Navigating API Governance at Scale: Striking the Balance Between Consistency and Autonomy: Richard Barker writes on how API governance aims to create valuable and usable API products by balancing consistent standards with team autonomy, much like national governance.

Protect Your Revenue with End-to-End Developer Observability: Conna Walsh's article highlights the importance of end-to-end observability in achieving robust application performance, which is crucial for rapidly growing tech companies and directly impacts customer satisfaction and business success through data-driven problem-solving.

The Deployment Bottleneck No One Talks About: Rak Siva points out that the necessary cloud SDKs create deployment friction due to complex infrastructure, cloud dependency lock-in, and extended debugging times but that a standardised layer like Dapr can resolve these issues with a unified API.

The Art of Deception: Luring Hackers With API Honeypots: According to Akansha Shukla, successful API honeypots require a deep understanding of attacker behaviour, not just basic fake endpoints. The deception lies in mirroring the valuable resources attackers seek, thereby drawing them in. This concept paves the way for a more detailed examination of design strategies for these deceptive APIs.

How to Mock AI APIs Using proxymock: Kristopher Sandoval highlights that AI APIs, as a leading technological advancement, introduce unique integration challenges as they transition to widespread adoption. He emphasises the necessity of building mock AI APIs to manage these complexities, noting that the underlying AI models make this process more intricate than traditional API mocking.

How to harness APIs and AI for intelligent automation: In this article, Susi O'Neill asserts that APIs have progressively established themselves as the fundamental structure of Artificial Intelligence systems, facilitating the seamless interconnection of data and utilities. She encourages readers to investigate how these interfaces may foster extensible and fortified training regimens for AI models and intelligent automation.

Tool

Proxymock CLI: A free CLI that automatically creates mocks and tests from API traffic.

Podcast

Visible APIs get reused, not reinvented: In this episode of The Stack Overflow Podcast, Frank Kilcommins discusses the difficulty of API discoverability in a crowded market, emphasising that even the best APIs are useless if developers can't find them. He argues that relying on passive discoverability risks others reinventing your solutions. Kilcommins then explores strategies and tools to overcome this "invisibility trap" and increase API visibility.

API Governance Consulting

Is poor API governance slowing down your delivery? Do you experience API sprawl, API drift and poor API developer satisfaction? I'll provide expert guidance and a tailored roadmap to transform your API practices.

•  API Product Delivery Assessment → Identify your biggest API delivery pain points.

• Ikenna® Delivery Canvas (IDC) & API Transformation Plan → Get a unified, data-driven view of your process.

• A3 Improvement Cycles → Instil a culture of scientific, measurable progress towards API governance.

• API Governance Team Model → Set up and improve your governance team to sustain progress.

• API Delivery Automation Guidance → Reduce lead time and improve API quality through automation.

Schedule your consultation here.