Chapter 3: Modeling APIs

Design and Build Great Web APIs — by Mike Amundsen

Importance of Design

Before we dive deeper into API development, let’s take time to understand the design aspect of it and how design can set the stage right for any API project.

Design helps us get a full understanding of the problem users are trying to solve, the workflow and data shared by various parties along the way, and the expectations of developers and users when they access our API. Design helps us lay the groundwork for the actual building of the API.

Understanding Norman’s Action Lifecycle

A former Apple fellow and co-founder of the earliest human-computer interaction design firm, Donald Norman was the first to use the phrase “user experience”. He introduced the concept called Action Lifecycle that can be directly applied to modeling APIs. It’s a model for the way humans interact with any object, whether on a screen or in the real world.

Norman’s Action Lifecycle is composed of 7 stages divided into 2 sections —

Bridge of Execution

• Plan
• Specify
• Perform

Bridge of Evaluation

• Perceive
• Interpret
• Compare

It talks about how planning, specifying steps to execute the plan and actually performing the action are crucial first steps towards completion of the goal. However at the same time, perceiving the outcome of the actions you performed, interpreting if it got any closer to completing the goal and comparing/evaluating if the end goal was reached is equally important.

This same concept can be applied to API development and a similar lifecycle can be asserted.

API Action Lifecycle: The RPW Loop

It is difficult to know exactly what happens in the perceive step or the interpret step when all we’re trying to do is model an API to solve someone’s problem. For example —a user requesting a web form on the internet. As an API developer, you can ensure the first 3 steps are completed, but how will you evaluate if after receiving the form the user achieved their end goal?

For this reason, we can simplify Norman’s seven-step model into 3 general actions that work for all the types of APIs we will need to model:

1. Request
2. Parse
3. Wait

This request-parse-wait(RPW) loop is much more prevalent in today’s internet world and that is exactly how the web works with the HTTP protocol, historically. You send a request, server parses it and you wait for a response. Same notion applies to API servers. Get a request from the client, parse the URL/body, process the request, sends a response and again wait for the next request to come in.

Modeling your API with the RPW loop in mind is a good idea. That means taking all you know about what your users are trying to accomplish (the goal), all the tasks they need to complete along the way (each of those in its own lifecycle) and how your users determine whether they’re making progress (comparing) and what it is that lets them know they’ve actually completed their work (met their goal).

More recently there are communication protocols like WebSockets which are used as real-time interfaces, but even they use the RPW loop with the difference being their wait times are very small and even smaller request/response messages.

Modeling your own API Lifecycle

The process of modeling an API involves collecting all the information you need in order to properly describe the tasks you want to accomplish, the data needed to get that work done, and the process or workflow needed to support all the tasks.

An easy way to do this is to use a simple pattern of discovery that involves 2 key steps you can repeat again and again until you’ve gathered enough information to work on the API directly.

• Map out the API workflow and identify the internal cycles.
• Write an API story document.

The API stories you write can be broken down into 5 sections:

1. Purpose: This is a short statement that defines the reason this API exists and what it does.
2. Data: This section lists all the data properties (inputs and outputs) involved in fulfilling the API’s purpose.
3. Actions: This section lists all the actions the API is expected to accomplish.
4. Rules: This section lists any rules the API is expected to enforce.
5. Processing: This section lists any processes the API is responsible for handling.

The first 3 sections are required elements or else you wont have a complete story. The other 2 sections may not be needed, depending on the API itself.

Going through these methodically and putting this all together will help you solidify your understanding before jumping into designing your APIs.