Let’s dive into the Bowling Alley framework to discover how it can inspire better API design by addressing the diverse needs of developers, crafting thoughtful and intuitive error handling, and emphasizing a minimal API surface area for seamless integration.

What’s the Bowling Alley Framework?

The Bowling Alley framework takes inspiration from the bowling experience—a game designed for players of all skill levels. In bowling, you have:

• Straight lanes: The path toward the pins that everyone is aiming for.

• Bumpers: Safety features for beginners to keep their ball from falling into the gutter.

• Smooth lane surfaces: Ensuring consistency so the ball rolls predictably.

• Guide rails: Subtle markers to help players stay on track without overbearing restrictions.

• Bowling aids: Extra tools like ramps for those who need additional support.

This framework translates beautifully to API design, where your goal is to create an experience that caters to all users, from novices to experts, while maintaining a clean, robust foundation. Additionally, the Bowling Alley framework has been effectively used in product onboarding to guide users toward achieving desired outcomes efficiently. By applying its principles, businesses can significantly improve user adoption and turn first-time users into loyal customers.

Let’s Apply This to API Design

Straight Lanes: A Clear Path to JBT (Job to be done)

Every API has a primary purpose, whether it’s retrieving data, processing transactions, or managing resources. Your API’s "straight lane" is its core functionality, and it must be:

• Intuitive: Users should immediately understand what the API does from its design.

• Well-documented: Clear examples and use cases provide a direct path for developers to hit their "pins."

• Consistent: Maintain predictable behavior across endpoints to reduce cognitive load.

By focusing on these fundamentals, you give your API users a clear target to aim for, no matter their skill level.

Bumpers: Onboarding Novice Developers

Many API designers put a lot of thought into the "bumpers"—features that help novice developers avoid failure early on. These can include:

• Step-by-step guides: Tutorials or quickstart guides tailored for beginners.

• Comprehensive error messages: Instead of vague errors, provide actionable feedback.

• Sandbox environments: Safe spaces for experimentation without impacting production.

While bumpers are crucial, overemphasizing them can lead to APIs that feel inflexible or overly constrained for advanced users. Remember, bumpers should guide without limiting experienced bowlers (or developers) who can play without them.

Smooth Lane: Consistency is Key

A smooth lane ensures the ball rolls predictably, and in API design, this translates to consistency across:

• Naming: Use standardized naming conventions for endpoints, parameters, and payloads.

• Predictability: APIs should handle similar requests in similar ways, without surprises.

• Error Handling: Design error responses as part of the core API design. Consider using standardized error codes, detailed messages, and suggestions for resolution.

Consistency builds trust with your developers, ensuring they know what to expect as they work with your API.

Guide Rails: Subtle Nudges for Advanced Developers

Advanced developers often find APIs frustrating when they feel boxed in. Guide rails, or subtle hints and optional constraints, can help them stay productive without feeling restricted. Examples include:

• Query options: Allow advanced users to retrieve only the data they need, such as through filtering, sorting, or projection.

• Optionality: Provide defaults for novices but allow experts to customize their API interactions.

• Comprehensive reference docs: Detailed specifications help advanced developers make the most of your API.

Bowling Aids: Specialized Tools for Unique Needs

Not every developer fits neatly into the novice or advanced category—many have unique needs that require tailored support. Bowling aids in API design can help bridge this gap by providing:

• SDKs and libraries: Prebuilt tools to simplify API interaction for popular programming languages.

• Code samples: Ready-to-use snippets for common use cases.

• Dedicated support channels: Forums or direct access to API experts for guidance.

These aids ensure you’re meeting developers where they are, regardless of their skill level or specific challenges. For instance, in my article about redefining the Apideck SDKs developer experience, I explored how thoughtful SDK design can significantly enhance usability, providing developers with a smoother integration journey and helping them achieve their goals faster.

The following image showcase how API design can accommodate developers at different skill levels (Novice, Competent, Proficient, and Advanced) while focusing on the job to be done (JBT).

• The lanes illustrate a path for developers based on their current skill state, ensuring that the API supports each group appropriately.

• Two bumpers: The API product bumper and API design bumper to guide API user to their JBT

Designing with Minimal Surface Area

To achieve API design excellence, your ultimate goal should be to create a straight, streamlined path for developers—much like a straight line in bowling. This means focusing on API surface area by exposing only the essential features and keeping everything else hidden behind the scenes. This minimalist approach simplifies learning, reduces the likelihood of errors, and minimizes maintenance overhead.

For instance, one of the guidelines Z and I implemented some years ago, helped adidas engineering teams achieve exceptional API design quality. By prioritizing minimal API surface principle, they were able to design APIs centered on core business capabilities while reducing complexity and elevating the developer experience.

To achieve minimal surface area:

• Start with the core API use cases and design for them first.

• Avoid adding API endpoints or features that cater to edge cases unless strongly justified.

• Use thoughtful abstractions to simplify complexity.

Conclusion

The Bowling Alley framework offers a nice mental model to designing APIs that cater to diverse developer profiles. By focusing on straight lanes, onboarding bumpers, smooth surfaces, subtle guide rails, and optional aids, you can create APIs that are both beginner-friendly and flexible enough for advanced users. Remember to design with minimal surface area in mind and integrate error handling as a core part of the process, not an afterthought.

1. Proliferation of APIs with Decreasing Costs

The demand for APIs continues to surge as organizations increasingly view them as critical enablers of innovation and efficiency. Notably, 63% of developers now produce APIs within a week, a dramatic increase from 47% in 2023, signaling a shift toward faster production cycles driven by advanced tooling and streamlined processes.

• Reduced Barriers: The availability of low-code and no-code platforms, along with robust API design tools, has democratized API creation. This enables even non-technical stakeholders to contribute to API development, further reducing costs.

• Business Impact: Companies are leveraging APIs to scale operations rapidly. For instance, APIs now drive over 75% of total revenue for 21% of organizations, making them indispensable assets.

• Global Growth: API usage is expanding globally, with developers from 266 countries contributing to the ecosystem. Emerging markets are becoming hubs for innovative API solutions.

2. AI-Powered API Management

Artificial intelligence is revolutionizing how APIs are managed, from creation to consumption. AI-Powered tools demonstrate the transformative potential of AI by automating tasks such as generating comprehensive documentation, analyzing API usage patterns, and identifying performance bottlenecks.

• Real-Time Insights: AI enables continuous monitoring and predictive analytics, allowing teams to anticipate failures and optimize performance proactively.

• Enhanced Governance: AI-driven governance ensures compliance with industry standards while reducing manual oversight. Automated checks for security vulnerabilities, deprecated endpoints, and adherence to design principles are now integrated into the development lifecycle.

• Future Direction: Expect AI to play a larger role in API security, using behavioral analysis to detect and mitigate cyberattacks before they occur.

3. Redefining API Consumption with API Agents

API agents represent a significant paradigm shift in how APIs are consumed. Unlike traditional consumers—primarily human developers—API agents are autonomous systems designed to interact with APIs programmatically, executing tasks with minimal human intervention.

• Design Considerations: API providers must now focus on creating APIs that are optimized for machine-to-machine interactions. This includes:

  • Structured Responses: Consistent and predictable data formats to reduce processing overhead for agents.

  • Error Handling: Clear and actionable error messages to allow agents to recover gracefully.

  • Performance: Low-latency APIs to support real-time agent operations.

• New Use Cases:

  • API agents are powering applications like intelligent supply chain management, automated trading systems, and IoT ecosystems, where rapid, autonomous decision-making is critical.

4. The Rise of SDKs as the New Interface

SDKs are emerging as the primary layer for abstracting API complexities and providing an enhanced developer experience. In 2025, SDKs will no longer just simplify API consumption but will become integral to building scalable and maintainable applications.

• Developer Empowerment: SDKs will offer features like AI-assisted debugging, automated code generation, and built-in testing utilities to accelerate development.

• Customization: Advanced SDKs will allow developers to tailor API consumption to their specific needs, with features like modular integrations and custom data transformation.

• Smart SDKs: We will see more and more advanced usages handled out of the box, like smart API retries, or automatic discovery of API capabilities.

5. Unified APIs to Accelerate Integration

Unified APIs like apideck consolidate multiple API functionalities into a single, cohesive interface, enabling faster and more efficient integrations. This approach is becoming increasingly popular as companies prioritize operational efficiency and time-to-market.

• Benefits:

  • Simplified Integration: Reduces the need for developers to interact with multiple APIs, lowering the learning curve and maintenance overhead.

  • Faster Onboarding: Unified APIs provide a consistent experience, enabling teams to integrate new services in days instead of weeks.

• Real-World Impact: In industries like accounting and e-commerce, Unified APIs are helping companies scale their offerings globally by simplifying partnerships and integrations.

6. Shift-Left API Governance

Traditional API governance approaches, often implemented late in the development cycle, are giving way to shift-left governance practices. These integrate governance policies directly into the development process, ensuring compliance and consistency from the outset.

• Automated Compliance: Tools like Postman Collections and CI/CD pipelines now enforce design standards, security policies, and versioning practices automatically.

• Developer-Centric: By embedding governance into developer workflows, teams can avoid the friction and delays associated with traditional governance models.

• Broader Adoption: Organizations adopting shift-left governance report faster production times and fewer API-related issues in production.

7. Growth in the API Consumption Ecosystem

The API provider space is becoming saturated, but innovation is thriving in the API consumption space. New tools are addressing challenges like discovery, testing, and observability, making it easier for developers to adopt and integrate APIs.

• API Hubs: We will see more platforms centralizing API discovery, enabling developers to explore and test APIs from a single interface.

• Observability Tools: Advanced analytics and monitoring tools provide deep insights into API performance and usage, helping teams optimize their integrations.

8. Monetization and Strategic Value

APIs are transitioning from backend utilities to core business products. The API-as-a-Product model is driving significant revenue for organizations, with 62% monetizing their APIs and many leveraging them to build strategic partnerships.

• Subscription Models: Tiered pricing and value-based subscription plans are becoming standard for monetizing APIs.

• Partnerships: APIs are serving as gateways to strategic partnerships, enabling businesses to co-create value and expand their market reach.

• Ecosystem Expansion: API monetization strategies are driving the creation of marketplaces and developer communities, further increasing adoption.

The Road Ahead: The API-Driven Future

In 2025, APIs will be at the heart of every digital transformation strategy, driving agility, scalability, and innovation. As the ecosystem matures, the focus will shift from merely creating APIs to enhancing their usability, governance, and monetization. By aligning with these trends, organizations can unlock new opportunities and remain competitive in an increasingly API-centric world.

I’ve finally found my answer by grasping the significance of ‘quality‘ in Japanese culture.

Zeno Rocha describes two kinds of quality :

• atarimae hinshitsu (当たり前品質)

• miryokuteki hinshitsu (魅力的品質)

Atarimae hinshitsu is the idea that things should work the way that they are supposed to.

Miryokuteki hinshitsu, on the other hand, is the idea that things should have an aesthetic quality. It's basically the kind of quality that fascinates you!

Whether you’ve had the privilege of dining at Jiro Ono’s restaurant or have immersed yourself in the ‘Jiro Dreams of Sushi‘ show, you’ll find this fascination and captivating quality.

Roget Ebert captures this essence by concluding:

While watching it, I found myself drawn into the mystery of this man. Are there any unrealized wishes in his life? Secret diversions? Regrets? If you find an occupation you love and spend your entire life working at it, is that enough? Standing behind his counter, Jiro notices things. Some customers are left-handed, some right-handed. That helps determine where they are seated at his counter. As he serves a perfect piece of sushi, he observes it being eaten. He knows the history of that piece of seafood. He knows his staff has recently started massaging an octopus for 45 minutes and not half an hour, for example. Does he search a customer's eyes for a signal that this change has been an improvement? Half an hour of massage was good enough to win three Michelin stars.

Roget Ebert

To build this fascinating quality, Jiro Ono was extremely focused on his customer’s perceptions.

Similarly building an awesome developer experience means you go beyond the functional part and focus on your developer’s perceptions that trigger their positive emotions (fascination, happiness …)

Understand your developer’s emotions

I believe that understanding the developer’s emotions and triggers is a great approach to enhancing DX. Abrahamsson, Graziotin, and Wang also confirm this belief as they demonstrated an empirical correlation between the Affective States of Software Developers and their self-assessed Productivity.

For more than thirty years, it has been claimed that software developers are essential when considering how to improve the productivity of development process and the quality of delivered products. However, little research has been done on how human aspects of developers have an impact on software development activities. We echo a call on employing psychometrics in Software Engineering research by studying how the affective states of software developers - emotions, moods, and feelings - have an impact on their programming tasks.

Abrahamsson, Graziotin, and Wang Paper

Re-design your Developer Journey

As developers interact with your products and immerse themselves in your environment, they traverse a virtual path that leads them from point A to point B (desired outcome).

We can recognize two sides within the developer journey path:

1. How your developers engage with your environment (e.g. developer community, team, organization, devRel program…)

2. How your developers interact with your systems to accomplish their tasks (code base, documentation, landing page, tutorials…)

Your developer intends to reach the destination faster and enjoy the journey by interacting with your environment and systems.

Every interaction serves as a step toward shaping the perceptions of your developers.

To optimize your DX, you need to focus on re-designing these steps:

1. Flag each step with a color:

   1. Red: Friction felt by developers and prevents them from achieving the desired outcome. (e.g. critical recurrent bugs)

   2. Amber: Friction that slows down your developers from achieving the desired outcome. (e.g. developers can find some manual workarounds)

   3. Green: Zero friction

2. Minimize the number of steps

3. Fix the Red and amber steps

Subscribe now

Divide and conquer your Developer Journey

Getting your developer journey right is a challenging task, It entails different stages. The nature and number of stages might be different and tightly coupled with what kind of developers you are targeting, for instance, internal developers will experience different stages than external developers.

Suppose you're managing an Open Source API or library. Employing a divide-and-conquer strategy involves outlining the essential stages that shape your developers' journey. Typically, three stages will be necessary:

• Onboarding

  • Objective: Reduce the time it takes for developers to get value from your product.

  • Steps

    • Getting started guides / quick start guides

    • Hands-on tutorials

    • Use-cases

    • Guided tours and checklists

    • …

  • Metrics

    • Time To First “Hello world“

    • Completion rates for setup / interactive tutorial

    • Number of downloads/installations

    • Positive feedback on the onboarding experience (NPS)

• Adoption

  • Objective: Reduce friction and build trust with your developers

  • Steps

    • Documentation

    • Sandbox / Playground

    • Debug / Error management

    • Changelog

    • Support

    • Webinars / Events

    • …

  • Metrics

    • Active product usage

    • Number of created assets (e.g APIs created)

    • The time it takes a user to fix an error

    • Positive feedback on the onboarding experience (NPS)

• Contribution

  • Objective: Increase the number of active contributors and maintainers

  • Steps

    • Documentation

    • Contributors and maintainers mentorship program

    • Ambassador program

    • Webinars / Events

    • …

  • Metrics

    • Time to first PR review

    • Number of active contributors/maintainers

Wrap up

By embracing the principles of quality, understanding the developer’s emotional aspects, and strategically redesigning the developer journey, you can create an exceptional developer experience that fosters fascination, happiness, and productivity.

In the following video, Jiro and his son share the secrets of applying these principles to make the best sushi in the world.

👉 If this post prompts you to reach for your chopsticks, feel free to share it! Or click the ❤️ button on this post so more people can discover it on Substack 🙏

This post is part of APIFutures, a community-led, collaborative effort to identify the top challenges and opportunities facing the API economy in 2024.

In the past decade, I’ve witnessed APIs evolving from point-to-point integration to sophisticated API products while supporting different organizations in scaling their API practices.

Six years ago, I was leading the API transformation at Adidas as a way to kill 6000 point-to-point legacy integration interfaces. That was like fighting a multi-headed dragon.

Subscribe now

We’ve learned that killing 70 years of Adidas integration legacy is tough and we decided to make building APIs faster and cheaper than point-to-point integration interfaces. I’ve learned as well that scaling APIs is more about how you build a system where API users can break rote habits.

“A worker is asked: “Why did you do it this way ?” The answer, “Because that’s the way we’ve always done things” The answer frustrates every good boss and sets the mouth of every entrepreneur watering. The worker has stopped thinking and is mindlessly operating out of habit” Rayan Holiday

To scale your APIs you need to ask four core questions consistently.

Have you established a sense of urgency?

Do you remember the collapse of Blockbuster (once valued at $4.8 billion), that is a typical illustration of not establishing a sense of urgency and adapting to change.

Blockbuster is a typical example of “mindlessly operating out of habit” and avoiding complacency.

But what does this mean for us “API leaders”? In practice, we need to: 

1. Feel the urgency: The best way to establish a sense of urgency is to feel it yourself, for instance, I’ve spent some time with BackMarket engineers while fixing API incidents to understand why we had a high MTTR (Mean time to recovery), and I’ve also tried to build an integration and feel what a bad DX (developer experience) look like.

2. Communicate the urgency: Once you have some facts and collected key insights, everyone should know about them and get a clear commitment to change.

Is your API vision good enough?

A good API vision is not just inspirational but a catalyst for change, your vision shouldn't be just a boring statement but a well-documented desired state. Additionally, ensure that your vision is created in a participative way otherwise the resistance to change will increase.

For example, at Backmarket, to guarantee a better alignment with their team goals and new business requirements, the API Chapter challenged and revisited the API vision every 6 months.

How is my organization supporting the API Vision?

The essence of a supporting organization is the ability to easily iterate and adapt whatever governance model you use. 

The key to scaling your APIs is adopting a decentralized decision-making approach and empowering your teams to make local API decisions.

For instance, BackMarket had inconsistent API errors that impacted DX (Developer Experience) score, so we picked HTTP problem detail standard. A naive model was to create a Pull-Request in our common API guidelines, get it approved, and present it in our API community of practice and different chapters. This didn’t scale well as some teams didn’t commit to this change that was painful to implement, then we delegated this decision to a “Working group” to make a second DX-friendly iteration by building an API Error library and implementing HTTP problem detail standard.

To go further we scaled our API governance model by creating API champion roles in different squads. The API champion was responsible for tracking his squad's API maturity, making local API decisions, and contributing to common API guidelines.

How do you sustain the change? 

Maintaining a change over time is like quitting smoking! Insights from the realm of personal development show that to adopt good habits you need : 

1. To make your new habits easy to use

2. A rewarding system

3. A strong commitment to change

Let’s take the HTTP problem detail standard adoption example, I’ve failed to get the commitment of some teams as we simply lacked the second and third ingredients. I’ve learned that any change should integrate this narrative and ensure systems are in place to support it.

Another example is the trend we see in the API tooling space where you can directly author your API specifications like AsyncAPI and OpenAPI from your favorite IDEs.

In the upcoming decade, we will see more and more vendors bringing their capabilities closer to engineers' SDLCs (software development life cycle). 

Wrap up

To wrap up, here are your 3 core questions to ask this year:

1. Have you established a sense of urgency?

2. Is your API vision good enough?

3. How is my organization supporting the API Vision?

4. How do you sustain the change?

👉 If you enjoy reading this post, feel free to share it! Or click the ❤️ button on this post so more people can discover it on Substack 🙏