Chapter 4: Designing APIs

Design and Build Great Web APIs — by Mike Amundsen

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 constant is the design process or method.

Design helps you bring consistency and compatibility to your API program. Two key elements for any successful design program are —

• 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.

APIs are really meant to do 2 things —

1. They need to match people’s needs
2. They need to support a viable business strategy

It is not a good idea to set out a design and build a bunch of APIs without knowing there is an audience for them and there is a business problem to be solved. When you start with a problem, it is easier to measure your success. And measuring success is how you make sure your API supports a viable business strategy.

API Design Method

Assuming you have gathered lots of information from key stakeholders, that you have copies of forms and worksheets, and that you’ve built up simple flow diagrams and other assets, its now time to turn those interviews and information into an API design.

Four steps to API design —

• Descriptor: Review all the names of the data and action elements and, where needed, convert them into the names already understood in your API program.
• Diagram: Convert your notes on workflow and internal cycles into something visual people can understand.
• Definition: Create a machine-readable API definition document that developers can use as a starting point for their implementation.
• Documentation: Write basic reference documentation for both service developers and service consumers (those using the API in the future).

Identify your API Descriptors

The first step in our API design method deals with identifying the names we’ll use for all our data elements and actions. These are called descriptors since they’re meant to describe the contents of the data elements (for eg. companyName) and describe the action a developer would be taking (for eg. approveUser). While the actual name we use isn’t too important, what is important is to use the same name (descriptor)for both data and action identifiers.

Another important aspect of focusing on the descriptors in our API design is to make sure the actual names we use are well understood by people not just within your current team but also other company-wide teams including any future employees.

Something like Schema.org can be used as a validating source for such descriptors. Schema.org is a joint effort by Google, Microsoft, Yahoo and Yandex to create a set of shared vocabularies that can be used by a wide range of web developers.

Another thing to keep in mind is that you should normalize your API identifiers against one or more of these well-known vocabularies.

Creating your Sequence Diagram

The second step in the API design method is to create a visual diagram that shows the general sequence of events. This is an important part of any good API design.

A visual representation of the workflows and internal cycles gives a clear idea of what actions will be available and what data must be passed back and forth when using the API.

Good understanding of the differences between the resource state and transitions (actions) is equally crucial along with identifying the right parameters to be sent to the API.

There are various tools online which can be used for sequence diagramming.