Can Agile Teams Have a Design-First Approach to APIs?

Some things just don’t go together, like finding a decent cup of coffee at any tech event. (Honestly, I’ve just accepted that the better the presentations, the worse the coffee will be.) But sometimes, things fit in a way you don’t expect, yet the combination actually works.

That’s how it felt when we were rethinking how teams could build and manage APIs with Kubernetes: Why can’t we have great coffee and great presentations? Why can’t teams iterate and experiment as they build? And that’s why we’re all-in on design-first when it comes to APIs. Hear me out!

Design-First

When you hear design-first, alarms start going off, right? It’s going to be architects and analysts creating long contracts, multiple spreadsheets or documents, and countless meetings about what we are going to build at some point.

Heavy investment in design usually leads to multiple surprises and unforeseen issues in the project, not to mention a gulf of disconnection between the teams involved as learning during development strays from the master plan. The whole premise goes against agile principles.

But what if we made the design process itself agile? What if we leveraged the OpenAPI specification to whip up the smallest version of an API (some might call it an MVP), and spin up a mock with nothing on the backend, just to test it out?

Knowing the response, your team could collaborate easily and iron out any issues that arise as you prototype instead of having to tackle them as you build.

Agile Principles

To understand the resistance to design-first, we should look more closely at agile principles. Back in 2001, a bunch of industry leaders got together for the weekend and created the Agile Software Development Manifesto, an alternative to documentation-driven, heavyweight software development processes. This boils down to four key values:

• Individuals and interactions over processes and tools
• Working software over comprehensive documentation
• Customer collaboration over contract negotiation
• Responding to change over following a plan

Agile teams work together in an iterative manner, collaborating to create working software and responding to changing needs as they arise. They don’t get bogged down in extensive negotiations over contracts, writing documentation or sticking to an inflexible process. And they definitely don’t require documents or detailed requirements to get started.

OpenAPI

If we’re talking about API development, especially RESTful APIs, we can’t gloss over the OpenAPI specification, maintained and driven by the OpenAPI Initiative. Originally based on SmartBear’s Swagger specification, the OAI is a standardized, vendor-neutral specification describing APIs.

Leveraging the OAI as a design tool means that your design document becomes a development tool that describes both the functionality and operational features of your API. Plus, you can use it to generate docs as you make changes.

In fact, at KubeShop we actually center our own API workflows with OpenAPI at the heart, as a single source of truth for both function and operations, so we can do away with additional configuration files because we hate complicating stuff.

Design-First Approach

Following the principles of agile development, and leveraging the OAI, design-first sees teams designing APIs before development begins — spinning up mocks, taking a look at the response and then collaboratively creating contracts to work against.

Design-first should be fast. API specs should be turned around quickly, ideally in hours or days, and prototypes (or mocks) of the API should lead the design conversation and speed up building the final product.

A Case for Kusk

At Kusk, we got tired of spreadsheets and trying to work in siloed teams. We’re after true agility, so we created a solution for it: Kusk Gateway. Our Ole Lensmar, writing about its beta release, wrapped up Kusk perfectly:

“Kusk Gateway is an open source ingress controller/API gateway that makes your OpenAPI definition the source of truth for both functional and operational aspects of your APIs, enabling an iterative design-first approach to API development with Kubernetes.”

We wanted to create a tool that would shift the design process to the center of the API development workflow. With Kusk Gateway, the API gateway is aware of your OAI definition and can see what a response would look like to generate a mock response for the end user. That way, working in parallel, your backend team can start building the real API — achieving a faster, no-code prototyping! This approach will also enable collaboration between product and consumer teams, who can work together on an emergent design while building a prototype of the API.

These prototypes can be iteratively substituted with actual backend functionality as it is developed. Take a look at this great tutorial from our Abdallah Abedraba on using Kusk Gateway on enabling rapid prototyping development.

Our vision is a tool that enables iterative development, eases collaboration and reduces the impact of dependencies, so you can do away with endless design drafts, spreadsheets and those awkward meetings that leave you worried about going to the team offsite retreat because you’ve butted heads with far too many stakeholders.

With the OpenAPI definition as the source of truth for both functional and operational aspects of your APIs, it effectively becomes your configuration and documentation. Your developer teams can feed the API’s specification to Kusk and have ingress resources ready to go — always up to date with any changes being made by developers.

Give Kusk Gateway a Go

Take a look at the Kusk Gateway GitHub repository and download the latest release. Installation instructions and documentation are available there as well. Plus, if you have any questions or ideas, please feel free to join our Discord server and get in touch.

And if you’re at KubeCon+CloudNativeCon North America this October, come say hello and commiserate about tech event coffee with us!