Designing Great Web APIs (2015)

Chapter 3. The Design-First API Process

Traditional software development is often focused on internal development teams that have access to the source code that makes the software function. Or, at the very least, they have access to the internal developers and data administrators to ask questions.

Web APIs, however, are more social in nature. They require collaboration between the developers consuming the API and the developers that built the API. They only have the API design and documentation to guide them. Developers consuming an API do not have access to the source code, database diagrams, or an internal knowledge base on why the API operates a certain, quirky way. They cannot copy-and-paste the source code for an API and make the changes they need to get their job done.

This means that our goals for our API design need to reflect simplicity and clarity and to anticipate the needs of developers and the end users who will indirectly consume the API from a web or mobile application. This is a difficult challenge for any team, no matter how experienced they may be with the particular software or business domain. Therefore, heavy emphasis should be placed on the API design process, including how your team translates product requirements.

This chapter provides a process and some guidelines for API modeling and design that your team may wish to incorporate into their process. Feel free to adjust as necessary to support your specific organizational requirements.

User Interface Wireframes to Drive API Design

In the case of an API that is being developed in tandem with a mobile or web interface, wireframing the user interface will help drive a top-down view of how the API will be used. The wireframes won’t define every required feature of the API, but they will focus on the key goals of end users: what they will do and how they will do it. This will have a large impact on the API, as often the user interface requires more complex interactions that the API will need to support.

While many APIs start with simple data-access functionality, the user interface will expose the gaps in your APIs as they need to perform more complex tasks. It will also expose the number of API calls that will be required to accomplish a given task. This is especially important with regard to mobile applications, where every HTTP call to an API occurs over an unreliable cellular network.

As we will discuss later, a simple wireframe or static mockup of the screens can help validate your API design. Be sure to schedule time into your project plan to design any web and mobile screens, preferably in time to help validate your API design.

API Modeling

Just as a beautiful web design begins from a wireframe, a great API design begins with modeling. The goal of API modeling is to translate the product requirements into the beginnings of a high-level API design. API modeling ensures that both developers and end users have their goals met.

The API modeling process is comprised of five steps:

1. Identify the participants, or actors, who will interact with your API.

2. Identify the activities that participants wish to achieve.

3. Separate the activities into steps that the participants will perform.

4. Create a list of API methods from the steps, grouped into common resource groups.

5. Validate the API by using requirements artifacts to test the completeness of the API.

The process is designed to be iterative, allowing you to return to a previous step if you discover that something is missing or needs to be adjusted. Let’s look at how to perform each step.

Step 1: Identify the Participants

The first step is to identify the participants, sometimes called actors, who will interact with the API. Unlike a user interface, an API design must factor in both humans and non-humans who may interact with your API. Some examples include:

§ System administrators (i.e., your company’s administrators)

§ Account administrators (i.e., your customer’s administrators)

§ Users of the system, including their various roles (e.g., users, managers, and moderators)

§ Internal or external software

§ Other Internet-connected devices

For each participant, you will capture their name and perhaps a short description of what they do (see Table 3-1).

By considering the different types of participants, it will help you consider your API design from a variety of intended uses.

Step 2: Identify the Activities

Activities are the outcomes that your participants will expect your API to provide. These activities focus on the job to be done, not how to do it. We will capture the steps required to accomplish the activities in our next modeling process.

Although your API may focus on only one activity, most APIs must support more than one activity to deliver value to developers. If you find yourself with only one activity, try asking what each participant is trying to achieve. Most likely, you will find more than one activity will be required of your API once you evaluate the activities for each of your participants identified in step 1.

For each activity, capture a short name, description, and the participant(s) that will be involved in the activity (see Table 3-2).

Step 3: Separate the Activities into Steps

Once you have a list of activities, it is time to break them into steps. Each step may involve one or more participants but must be executed by a single participant at a time.

You may find that you may be missing some details about how an activity should be performed. This is an indicator that you should involve one or more subject matter experts (SMEs) who can provide greater insight and details into how the system should work. These experts may be business analysts, customers, and/or quality-assurance teams familiar with the requirements.

For each activity step, capture the activity name, a short name for the step, a description, and a list of participants who may perform the step. Table 3-3 is an example of documenting the activity steps for the “manage project tasks” activity in the previous modeling step.

You may notice that you see recurring patterns or steps across activities. That is expected and may provide insight into possible API design and/or code reuse.

Step 4: Identify the Resources and Candidate APIs

Once you have the activities and steps identified, you will begin to see specific business entities emerge. These are your resource candidates that may become actual API resources. Others may appear to be resources but may instead be activities that will be performed outside of the API itself and therefore won’t become actual API resources. Since this is the modeling phase, that is perfectly fine. Our API design process will help filter out these unnecessary items.

Because this is the modeling and not the design phase, we do not want to focus on the HTTP specifics. Instead, focus on the high-level API only. The details of how you will implement the API, including the specific URLs, HTTP verbs, and response codes will emerge as we move into the full API design process. Table 3-4 is an example of how to document the project tasks API that we have identified as a result of our API design model.

Step 5: Validate the API Model

Once you have an API model defined, you can use the model to validate that it meets the requirements of internal developers, partner or public developers, and the end user. There are three techniques that can help validate your API model:

The API walkthrough

If you have mobile or web mockups, walk through each screen to determine which API will be used to satisfy the data being displayed or functionality being performed. Revisit any areas that you may have missed to ensure that you have a complete API model.

Use-case validation

Using existing use cases, step through each one to identify any gaps in your API. This is especially useful if user interface mockups haven’t been completed yet, or if some of the API will not have a user interface associated with it. This is often the case for APIs designed for machine-to-machine integration rather than end-user functionality.

Business-process diagrams

For APIs that will be supporting business-workflow processes, first diagram the workflow(s). For each step in the workflow, map your API model to each step to ensure that you can accomplish all necessary aspects of the workflow.

As you validate your APIs, look for methods that are missing. You may also want to make notes about APIs that have dependencies on other APIs or that may experience heavy usage. While not necessary, this may guide some of your decisions as you move into the design and development phases.

Next Step: Detailed API Design

With the API model complete, we now have a sketch of what our API will look like. The next step is to detail the design by applying HTTP and REST principles. We will cover this in the next chapter.