Join our - Lead the Future of API Dev: A New Approach with Blackbird -Webinar on September 19thRegister Now

Back to blog
API DEVELOPMENT

The Secrets of API Design and Development with API Intersection’s Jason Harmon

Kay James
January 9, 2024 | 5 min read


"It's about slowing down to speed up, but with that pressure to grow, so many tech leaders look and say, ‘APIs are a competitive advantage, so let's go do build that…and then 6-12 months into building a program they go, 'Okay, we're not going faster. What's happening?' It's like, no, you got to slow down to speed up when you're building platforms,"
Jason Harmon, Stoplight CTO

On the latest Livin' On the Edge podcast episode, I interviewed Stoplight CTO and host of the API Intersection podcast, Jason Harmon. With over two decades in the industry as a leader in the API design space, Jason brought many valuable insights to the table on the importance of intentional platform design, the need to slow down for sustainable growth, and the role of APIs in driving innovation. Tune in or catch the main takeaways below.

The Secrets of API Design and Development with API Intersection’s Jason Harmon


Strategic Approach to Platform Design:

We already knew that platform engineering was going to be the hot topic of 2024, but with this, Jason says, comes the great significance of being intentional when designing a platform, not just doing it for the sake of keeping up with the trends.

Rather than rushing into development, Jason stressed the need to take a step back, analyze the puzzle pieces, and understand how they fit together. This strategic approach, though time-consuming, ultimately leads to smoother development and better tooling.


"When building a platform for anything, especially APIs, step back and ask yourself, ‘What is the picture this paints as a whole?’ That's going to be hard. It's going to take a minute. But once we start building that, every step, things get easier, things get smoother, the tooling gets better,"
shares Jason

Good platform design is also a way to democratize development, enabling teams to build products quickly without the need for an extensive engineering team. Jason highlights, however, that “good democratization is achieved through well-designed APIs and platform architecture first and foremost.”

Additionally, when designing a solid API management platform, iterative improvement is key. Continue to chip away at the design, even if it involves arguing over seemingly trivial matters. Over time, these incremental improvements lead to a more robust and well-designed platform. To get iteration right, Jason emphasizes collaborating across various disciplines—designers, product managers, tech writers, and engineers. Building a successful platform requires a multidisciplinary and collaborative approach.

Building APIs with a Growth Mindset: Design-First

That idea of taking a step back is taken a step further when we shift over to the realm of API design and development. In the API world, there’s a common misconception that APIs are a ‘quick fix for growth.’ Hint, that’s a slippery slope that plummets many CTOs down a path of no return, littered with zombie APIs and immense tech debt.


"I agree that while APIs can be a competitive advantage, the process of building them requires time and deliberate decision-making. There's a necessary balance between the pressure to grow and the need to design a platform that stands the test of time. You have to get the design stage right before launching any APIs,"
Shares Jason

Jason emphasizes utilizing the design-first approach, which focuses on designing the API's contract first before writing any code and involving all relevant stakeholders from the start to ensure all perspectives and use cases are captured early on. Again, this is about bringing it all who may have a stake in the API design including the documentation writers, the product manager, the consumer, and the developers all together.

Often development teams will default to a ‘code-first’ approach because that's what’s familiar and known, but starting with the design of the API first not only improves developer experience in its entirety but it also helps eliminate tech debt and friction later on in the API development process.

The Role of AI and No/Low-Code Tools in API Design

With the rise of no-code tools as well, many tech leaders are taking the same failed approach here of quick adoption without a true foundational understanding of their impact on API development. Don’t make that same mistake here, either! Jason acknowledged that no-code tools definitely have their place as prototyping tools, enabling quick MVPs and democratizing product development.


“However, I caution you against the assumption that these no/low-code tools can actually replace the magic that happens when multidisciplinary teams collaborate to build a bespoke solution. There is no quick fix,”
Shares Jason

That thinking applies to the rise of AI tools as well and their use in API development. AI is also not a ‘quick fix’ to all your technical problems, but it's beginning to play a significant evolving role in API documentation, design, and development.

For example, Jason shared with us the experience of using AI to generate the initial draft of API docs, or using it for boilerplate content. While AI aids in expediting certain aspects of the documentation process, it’s important to note that human involvement is still irreplaceable for creating engaging, user-centric products.

In the end, the approach is everything when designing a true API management platform. Whether it’s strategic platform design, the role of OpenAPI, or the evolving landscape of AI and low code tools, we both recognized that successful API development requires a multidisciplinary understanding and a commitment to collaboration starting at the design phase. For more insights on the Kubernetes world, APIs, and developer experience, visit our podcast page at https://www.getambassador.io/podcasts.

Advance Your API Strategy with a Design-First Approach.