NOTE: This article contains content extracted from Mike Amundsen's "Design and Build Great Web APIs", published by the Pragmatic Bookshelf. For more information or to purchase a copy, please visit http://www.pragprog.com.
Art, architecture, and design all rely on the unique traits of the individual in order to turn out the final result—the building, the canvas, the musical score, or the API. Even though the final results rarely look the same from person to person, artists and designers often share a similar method or style when they go through the process of creating their work. And it’s this process or method that can be described and standardized. When we all use the same general method, even when we come to different final results, those results are very likely to be compatible — they work together easily. This is the power of a good design process. It allows people to continue to think for themselves, to contribute in unique ways, and still come up with results that are compatible across the organization.
Creating compatible solutions is an important element of a healthy API program. In most companies, the API program will span many years, have lots of different people involved, and over time use several different technologies and products. Throughout all those changes, one of the things you can keep as a constant is your design process or method. By teaching your developers the same design method, you gain consistency without overconstraining their creativity.
A good design method also doesn’t assume any single technology stack or tool set. That means you’ll be able to grow an API program over time that’s built on the power of consistent design methods and not reliant on any one API format or protocol or other technical elements. In fact, a good design process makes it easier to change tooling over time without introducing incompatible implementations.
So design helps you bring consistency and compatibility to your API program. But how does that happen? Two key elements of any successful design program are these:
- Design thinking: The way people think about the process of designing an API
- Jobs to be done: A focus on the tasks your API users are trying to accomplish
Before jumping right into our API design method, let’s take a moment to review design thinking and jobs to be done in a bit more depth.
The phrase “design thinking” is used quite a bit in product design to identify a point of view and a collection of practices that help people think differently about the way they design and build products. Tim Brown, the one-time CEO of the design firm IDEO, describes design thinking as “a design discipline that uses the designer’s sensibility and methods to match people’s needs with what is technologically feasible and what a viable business strategy can convert into customer value and market opportunity”. The key words in that quote are “match people’s needs” and “viable business strategy.”
While we may not think about it much, APIs are really meant to do both those things. They need to match people’s needs and they need to support a viable business strategy. The people we need to pay attention to when designing APIs are often not just end-users but also developers. Knowing your audience well is key to creating APIs that do a good job of solving the problem. For example, designing APIs for internal use by your own team is different from designing APIs for developers working for your customers or partners. Each is likely to have a different point of view, a different set of skills, and different priorities.
Creating something that supports a viable business strategy or goal is important too. It’s not a good idea to set out to design and build a bunch of APIs without knowing there is an audience for them and a business problem to be solved. Just creating APIs to say you have APIs is not a viable strategy. At the same time, building APIs that no one asked for, that no one really needs, is also a bad idea. I’ve seen API teams work hard to get funding from leadership, then work hard to build and release generic APIs that no one requested, only to find that company leaders complain that the new APIs aren’t what they need and thus go unused. This isn’t a viable business strategy.
What does it take to build APIs that “match people’s needs” and support a “viable business strategy”? That is where the concept of “jobs to be done” can help.
Jobs to Be Done
An important reason to design and build an API is to solve a problem — to “match people’s needs.” In Chapter 3, Modeling APIs, we worked to discover the problem (onboarding new customers). In our case, the customer onboarding work is a job that needs to be done. That’s what Harvard professor and author of the books "Innovator’s Dilemma" and "Innovator’s Solution" Clayton Christensen calls “jobs to be done.” He says, “People don’t simply buy products or services, they ‘hire’ them to make progress in specific circumstances.” Translated into API terms, developers want to make progress (solve problems) and they’ll use (or hire) whatever APIs will help them do that.
This means that designing APIs to solve existing problems is essential. Every organization, large and small, has problems that need to be solved. Focusing on them and figuring out how APIs can help is a good strategy for a number of reasons.
First, when you uncover problems to be solved, you’re tapping into an opportunity to make things better. When you can create an API that makes work easier, safer, faster, and so on, that’s a win. Second, when you complete an API that solves a problem, it’s easy to know if you reached your goal. The truth is that sometimes our APIs don’t work as we expected and may not actually do a good job of solving the stated problem. When that happens, we need to learn from our attempt and then move on to design and build an API that does solve the problem. When you start with the problem, it’s easier to measure your success.
And measuring success is how you make sure your API supports a viable business strategy.
As mentioned earlier, it doesn’t make sense to invest a lot of time and money into an API no one really wants or needs. That’s why “matching people’s needs” is an important element of good API design. Another important element to good API work is making sure the design and implementation work makes good business sense. This can be a challenge since it’s common for API designers and developers to be a bit “out of the loop” when it comes to business details. In fact, I know many programmers prefer it that way. But in reality, all of us working on IT projects for our companies have a responsibility to make sure the work makes good sense both technically and business-wise.
While developers aren’t often the ones who decide business strategy, we influence what time and money goes into executing on that strategy. In my experience, there’s more than enough opportunity to improve the way companies use APIs in their business. In fact, the challenge is not in finding an API opportunity, the challenge is in prioritizing the many existing opportunities. And that’s a place where developer teams and API designers can help.
Starting an API project often represents a risk. It requires a commitment of time, money, and personnel. Working on one project can mean not working on other API projects. And the more time and money your API project consumes, the less is available for other projects. For this reason, one of the best things you can do when designing APIs is to reduce the risk incurred. You can do this by building an API that matches people’s needs and has enough flexibility built in to allow for small changes in the future without big costs. That’s a lot to think about. But as time goes on, I’ve found most API developers and designers get pretty good at balancing matching needs versus anticipating changes. We’ll see examples of this trade-off throughout the API design and build we’ll be doing in this book.