Chapter 1: Getting Started with API First

Design and Build Great Web APIs — by Mike Amundsen

Adopting API-First principle

The very first idea of API First Design was described as — 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.

Two key elements of API-First principle are -

• Focus on who’s using the API and what they want to accomplish
• Design the API first before you start to think about technology details

Third element of this pertains to the business side of things and that APIs exist to solve the business problems.

Using APIs to Solve Business Problems

Typically APIs are needed to solve the problems in 3 basic categories:

I. Reducing the time/cost of getting something done

API Solution: a) helps automate some existing process or b) is aimed to bridge the gap between teams.

For these kind of APIs, the design needs to be specific enough to solve the problem at hand and flexible enough to be modified in the future without causing more pain for the teams involved. Thus, this is a short-term fix with long-term support in mind.

II. Increasing the ease or likelihood of getting something done

API Solution: a) makes developers more productive and b) makes it easier to solve interaction problems for humans with building simpler UI/Single Page Applications (SPA)

These APIs are usually used to improve throughput or increase sales, user-signups and so on. They can get very complicated as the API matures on adding more features along with the growing business demands.

III. Solving a problem no one else has solved

API Solution: provides a fix to a problem no one has yet solved.

These are most fun to work on, but it can have its own challenges. Most of the times all the necessary components to build this API exists within the company but designing and implementing a composed API solution takes lots of attention to details and planning for possible failure.

Understanding APIs and Design

Knowing the target audience of your API and the kinds of problems those people want to solve is critical when it comes to creating APIs that meet the needs of your audience without jeopardizing the safety and security of your own company.

First principle tells us to design APIs without regard to the technology you might use to build it. That means we focus on the interactions in the API experience as well as the data behind it.

In fact, in well-designed APIs, the interaction is paramount. It’s important to first determine what tasks need to be done. Only then do you spend time figuring out just what data you need to pass back and forth for each interaction in order to accomplish the required tasks.

A really good process for supporting API-First design is to gather information and then document the list of actions. Once you complete the list, go back and start to list all the data properties you need to share for each interaction. And when you have all the information gathered, thats when the real design work begins.

In some cases, your API consumers will have all the data required ahead of time and you just need to plug the values into your API and execute a single call. In other cases, only part of the required data is available. When your API consumers don’t have all the data, they need helper APIs to fill in the blanks. Getting an understanding of the circumstances your API consumers are working with will help you design an API that allows them to solve their problems relatively quickly, easily and above all — safely.