Issue #65

As an engineering leader, you may want an assessment of your organisation’s approach to API design.  Is the right process – that is, the API design methodology – in place to lead the design and production of APIs that accelerate innovation and business agility [1]?  In this post, I’ll describe eleven criteria you can use in such an assessment. 

The first step to any kind of process improvement is to capture the current state of the process. When you have done that, these criteria can help you in your assessment of the process. As an example of this, in a recent post I discussed five API design methodologies; my intention is to provide a review of them, beginning with the Synergetic Blueprint [2]. 

Before I mention the criteria, I want to say that I will be using the term “platform API” to mean the digital interface of a business capability platform. This is usually described in one API description file (an API contract) containing one or more API operations. As I mentioned in my previous post, business capability platforms expose functions from the business domain. For example, in a banking platform, an operation to override the interest rate applied on an account. 

Having provided that context, here are the criteria I’ll use to review the API design methodologies based on product and engineering outcomes. 

How well does the API design method lead to platform APIs that are aligned with real user needs and requirements, resulting in high platform adoption [3] ? By “user”, I mean both humans and agents.

How well does the methodology encourage APIs to be designed for end-to-end workflows and orchestration across multiple capabilities? Are workflows identified and described during design? Does it support the design of task-oriented operations, event patterns, and explicit state transitions?  Does the process support the creation of executable workflow descriptions, retries and idempotency? 

This criterion matters because of the need for AI agents to execute workflows, and for composable, event-driven architectures. 

How much does the API design method encourage platform API reuse? Specifically, does it  reduce the probability of duplicated API builds?  

Without sacrificing API design quality, how long does it take to go from the approval for a new business capability (or from a new API request for an existing business capability) to an approved API design? 

How does the method facilitate the reuse of standardized domain data and bounded-context definitions, rather than creating inconsistent versions (e.g., multiple “Customer” objects in the same domain)? Does it help teams identify clear API boundaries? 

Furthermore, does the method incorporate requirements from the organization’s API style guide to ensure API design consistency? 

Does the method encourage creating APIs that can be evolved without creating backward incompatible versions (i.e. Breaking changes)? A poor methodology can lead to missed requirements, expensive rework and breaking changes later. 

Does the method support the creation of comprehensive API descriptions, workflow examples and usage patterns for a great developer experience (DX)?

How much does the method encourage “shifting left” on security concerns like authentication and authorization? Does it capture sensitive data concerns, performance/latency expectations, and abuse prevention requirements like rate-limiting at design time?

Does the method incorporate techniques for  getting feedback on the API design via mocking and early prototyping?

How much does the method encourage input and feedback from different stakeholders – consumers, security, product, and engineering – to ensure the design satisfies all parties? 

How easy is it to train a team on the API design methodology? Are there reusable templates, tools, training resources, or an active community available to support practitioners?

The table below summarises these criteria across six dimensions. 

When I review each methodology, I’ll use the following Likert scale. While any scoring is inherently opinionated, a Likert scale enables consistent comparison while preserving the nuance required to evaluate a complex API design process. 

1. AI assistance: I view AI-assistance as an enabler of outcomes rather than an outcome in itself. 

2. Observability: While critical, observability is primarily influenced by runtime architecture and implementation rather than design methodology. 

Regardless of the API design methodology your organisation uses, it is worthwhile to assess it based on the outcomes it achieves. This assessment provides the basis for continuous improvements and platform maturity growth. Having established these criteria, I will use them to review the Synergetic Blueprint in my next post. 

[1] S. Fishman and M. McLarty, Unbundling the Enterprise: APIs, Optionality, and the Science of Happy Accidents. Portland, OR, USA: IT Revolution Press, 2024. [Online]. Available: https://itrevolution.com/product/unbundling-the-enterprise/

[2] A. Junker and F. Lazzaretti, Crafting Great APIs with Domain-Driven Design: Collaborative Craftsmanship of Asynchronous and Synchronous APIs, 1st ed. Berkeley, CA, USA: Apress, 2025. 

[3] B. Pedro, Building an API Product: Design, Implement, Release, and Maintain API Products that Meet User Needs. Birmingham, U.K.: Packt Publishing, 2024. [Online]. Available: https://www.packtpub.com/en-gb/product/building-an-api-product-9781837630448 

API Trends in 2026 and Beyond: What’s Shaping the Future of APIs?: This article details how traditional routing is being replaced by contextual management, where gateways must now monitor token usage, AI prompts, and automated agent behaviour to ensure security and cost-efficiency in an "agent economy."

Coming to Postman in March: AI-native capabilities, a new API Catalog, and updated plans and pricing: The Postman Team announces a significant platform overhaul for March 2026, introducing AI-native capabilities and a new operational "API Catalog."

Map Your API Landscape To Prevent Agentic AI Disaster: Charles Humble explores the warnings of API expert Kin Lane regarding the risks of integrating agentic AI into immature API environments.

Using MCP For API Documentation Discovery: Kristopher Sandoval argues that MCP transforms documentation from a static resource into a "first-class context object" that supports developers.

How AI Changes Authentication & Authorization Models: Kay James shares that static API keys are insufficient for 2026 architectures, where AI agents act non-deterministically. They propose a move toward continuous, context-aware verification and the use of sender-constrained tokens to ensure that even intercepted credentials cannot be exploited by unauthorised actors.

Load Balancer Filter-Based Approach To Enable Distributed API Rate Limiting: Kalyanasundaram, T., Panchalingam, K., Jegatheesan, T., Wijayasiri, A., & Perera, S. (2025). In this paper the challenge of enforcing API rate limits consistently in distributed systems is addressed, where multiple load balancers and service nodes handle traffic. Rather than relying on single-node rate limiting, the authors propose implementing rate limiting at the load balancer using Lua filters that enforce global (client-specific) limits across all nodes. PDF here.

If you find this newsletter valuable, please share and forward it to your network.

LEAP 2026: Tyk's virtual conference on APIs, AI and the future of financial services. Date: March 12, 2026 | Location: Virtual

apidays Singapore: apidays Singapore will share insights on API monetization, security, AI-driven automation, and more. Date: 14 - 15 April 2026. Location: Marina Bay Sands, Singapore.

Apidays New York: Location: Convene 360 Madison, New York, Date: 13 - 14 May 2026

API Conference London 2026: The Conference for Web APIs, API Design and Management Date: May 11 – 15, 2026, Location: Park Plaza Victoria London, UK.

APIOps Helsinki Conference 2026: An API gathering in Finland for two days of focused strategy sessions, hands-on clinics, and peer-led community building. Date: June 2-3, 2026 | Location: Epicenter, Helsinki