2 Identifying API capabilities

This chapter covers

Analyzing use cases
Identifying unique and versatile operations
Ensuring alignment with user needs
Avoiding integrating overly specific consumer requirements
Avoiding exposing the provider’s inner workings

API design begins by analyzing users’ needs and identifying the API capabilities required to fulfill them. Identifying the appropriate API capabilities is crucial. As seen in section 1.2, an API with incorrect capabilities can make developing applications that consume it complex or impossible, wasting time and resources and potentially jeopardizing the API provider, even when the faulty API is private.

We’ll describe capabilities using plain English or any other natural language rather than programming interface language. This is because form follows function, a design principle that applies to buildings, kitchen appliances, applications, and APIs. An effective API design requires analyzing users’ use cases and identifying the generic operations to fulfill them and yet-to-be-discovered use cases before choosing the appropriate programming representations and data modeling. This simplifies discussions, streamlines the design process, and avoids creating complex or incomplete APIs that don’t meet user needs.

2.1 An overview of identifying API capabilities

2.1.1 Starting with the output of the Define stage

2.1.2 Analyzing what users need to achieve

2.1.3 Identifying versatile operations to achieve use cases

2.1.4 Keeping programming interface design concerns for later

2.1.5 Clarifying the subject matter and input

2.2 Introducing the API Capabilities Canvas

2.2.1 How does the API Capabilities Canvas work?

2.2.2 Tools to use along with the API Capabilities Canvas

2.3 Walking the nominal paths

2.3.1 Identifying users

2.3.2 Listing use cases

2.3.3 Decomposing use cases in steps

2.3.4 Determining inputs and success outcomes

2.3.5 Spotting missing elements with sources and usages

2.3.6 Analyzing the spotted elements

2.4 Walking the alternative and failure paths

2.4.1 Analyzing failures for each step

2.4.2 Adding alternative branches on each use case

2.4.3 Analyzing the alternative users and use cases