Designing Web APIs

Appendix A. API Design Worksheets

We’ve added these worksheets to accompany our hands-on design advice. The worksheets can be used to accompany the fictitious example from Chapter 5, or used repeatedly as templates for your own API designs.

Define Business Objectives

The Problem

Briefly define the problem and how it affects customers and the business.

The Impact

Define what success looks like for your API. What will the world be like after you’ve released your new API?

Key User Stories

List several key user stories for your API with the following template:

As a [user type], I want [action] so that [outcome].

1.  

2.  

3.  

4.  

5.  

Technology Architecture

Describe the technology architecture you’ve selected, along with the reasons behind your decision. You may wish to include charts or graphs showing the pros and cons of paradigms you’ve considered. Here’s an optional example table:

Table A-1. Technology architecture

Pattern, paradigm, or protocol considered	Pros	Cons	Selected?

API Specification Template

Title

Authors

Problem

Solution

Implementation

Give a high-level description of the implementation plan. You may wish to use additional tables or diagrams to describe your plan.

Authentication

Describe how developers will gain access to the API.

Other Things We Considered

If you considered any other API paradigms, architectures, authentication strategies, protocols, etc., briefly mention what you considered. ...