The Power of API First

Introduction

From my experience talking to companies around the world, IT programs that allow your teams to design and build great Web APIs are always powered by a set of shared high-level principles. It is this collection of principles that allow people from all points of view working from a wide range of technologies to all maintain a shared purpose and clear set of measures. I and my co-authors discussed this concept in the a chapter on API Governance in the book "Continuous API Management."

And one of the key principles that powers successful API programs leverages the power of the "API-First" approach. Like many successful endeavors, the idea behind "API-First" has many parents. 

A Short History

I first learned the idea of API First from Kaz Thomas in his 2009 blog post, "API-First Design". In that post he sums it up like this:

"API-first design means identifying and/or defining key actors and personas, determining what those actors and personas expect to be able to do with APIs."

It is important to know your "customer" and to know what they are trying to accomplish. This is valuable information no matter what you are working on!

I also like the definition API evangelist Kin Lane shared in 2014: 

"Before you build your website, web, mobile or single page application you develop an API first."

That's simple enough. Do the design work *before* you start coding. While not a profound point of view, it can be challenging for developers to resist the lure of writing code from the start. After all, most programmers "think in code" anyway. And there are times when pressure to produce output can overcome the desire for a disciplined approach. 

But here we have it in simple terms: 1) understand the problem, 2) know your audience, and 3) focus on the interface first. These three elements are the key to supporting a healthy API-First program in your organization.

The Three Pillars of API First

In my new book "Design and Build Great Web APIs" I devote an entire chapter to the principle of API-First and expand on the ideas of Thomas and Lane to dig a bit deeper into the three elements of solving business problems, knowing your target audience, and taking the time to support a design-driven implementation practice for your API program.

Understanding the Problem

It is important to remember that APIs exist to solve business problems. Whether that problem is shared by thousands around the world, a few hundred within your company or just a couple people on your local team, APIs are interfaces that should meet a well-defined need. 

Knowing the problem is the first step toward solving the problem. It is hard to succeed when you don't understand the challenge set before you. That means taking the time to ask questions and often go beyond the obvious. The Toyota Way teaches the concept of "Five Whys" as a method for iteratively asking "why" upon getting answers to your questions. Each "why" is meant to get closer and closer to the actual problem and to improve understanding.

Throughout this focus on the problem, teams can document and share their findings using informal (but fully accessible) ways like wikis, trip notes, and so forth. These notes will be handy as you move to the next phase in the API-First practice: Knowing the Audience

Knowing the Audience

Along with identifying the problem your API is meant to address, identifying the API's target audience is another critical step. There are lots of reasons for this. First, the type of person you expect to use your API will affect the way you design and build it. For example, if you're target audience for the API are a collection of Computer Science graduates using Java and C# you'll design a different API than one aimed at Android and iOS developers.  

And you'll need to think differently about the API if your target audience are external developers versus your own internal staff. You'll design the interface differently and document it differently, too. 

Finally, knowing how much time your target audience typically spends on your API will affect your build and design decisions. If you are expected full-time developers to spend all day with your API you'll need to design it differently than if your target developers are only doing API work "on the side" along with their regular jobs in finance, sales, marketing, etc.

It's common to collect this information into a series of personas or user profiles to use as references when you are designing and building your API. There is no need to get overly elaborate with these profiles. Just make sure you have some notes easily accesible somewhere that offer a clear statement of your target audience.

All this talk about business problems and target audience keeps coming back to the same issue: you need to be actively designing your API.

Driving the Design

Collecting information on the details of your business problem and your developer audience are all in the service of driving the design of the API toward a goal: to create an API that does a good job of meeting a need for a known community. This is where "design thinking" comes in.

The notion of design thinking (DT) has been around for at least fifty years and I encourage readers to check it out in more detail. A common way to talk about DT in the product design world is described by the people at IDEO as the intersection of Desirability, Feasibility, and Viability. What is the desired outcome (solving the business problem), what is actually feasible (e.g. do we have the skills and tools to pull of the solution?) and, finally, how viable is the solution (e.g. can we afford the time and resources it will take to build it? Will people use it?).

There is no mathematical way to identify the ideal inspection of desirability, feasibility and viability, but there are processes you can use to help you identify something that will work for your team and your company. Prototyping, testing, and building "mock" APIs are all things you can do to actively design your APIs in ways that increase the likelihood of success in your API program.

Summary

Adopting an API-First approach to creating your APIs means making a commitment to learning. Learning about business problems, about developer audiences, and learning to think and act "like a designer". None of this is rocket science and all of it matters. Taking the time to get it right at the start can save you time and money.

As Mary Poppendieck, one of the gurus of Lean Software Development, states: "The biggest cause of failure in software-intensive systems is not technical failure; it’s building the wrong thing."