The Role of Product Management in API Design

Published in

Capital One Tech

6 min readApr 3, 2018

Successful APIs, whether they are external products or internal glue, require strong product management. However, given an API’s ephemeral nature, product managers may have difficulty with how to proceed. Done poorly, poor API product management results in a product that doesn’t meet the needs of users. Adoption will be limited. Integrations, when they do happen, will be difficult. And correcting mistakes after development will remain a demoralizing and expensive proposition.

Martin Erikson, in defining the Product Manager role, defines product management as an expertise that lies at the intersection of tech, business, and UX. Martin quotes the book, Inspired, that states a product manager should “Discover a product that is valuable, usable and feasible.” What constitutes “valuable”, “usable”, and “feasible” for an API?

Valuable

At the most fundamental level, an API must provide a useful function. Determining what is useful and what is not is the first job for an API product manager.

Building for the Correct Audience

Product managers should understand the audiences, along with their unique concerns, that will consume an API. As Brad Fults mentions, these audiences may include, but are not limited to:

Decision makers evaluating competing API products.
Developers looking to get started.
Integrators attempting to debug a specific issue in an existing client.

Each audience has different needs. For the decision maker, is the functionality provided by an API the same — if not better — than other competitive offerings? Can a developer get started with an API easily, perhaps with nothing more than a CURL statement? Does the API return the type of error messages that, when things go wrong, makes it easy for an integrator to fix?

Finding those audiences and answering their needs are not a trivial exercise. A big part of a Product Management job is research and testing. Hackathons are a great place to validate assumptions and discover issues with an API design.

*Capital One DevExchange Hackathon — Denver, 2017*

API Design That is “Outside In” Not Reflections of Internal Implementations

An API design should align with the integrator’s understanding. Creating an interface constrained to the internal systems implementation is rarely a good idea. These systems, particularly those that have existed in legacy environments, are a complex aggregation of shifting business priorities, technical advancement, team experience, etc. Exposing years (if not decades) of ‘dirty laundry’ at once significantly increases the barriers to comprehension and adoption.

Clear Ownership

Product management includes a degree of ownership. The ownership component that integrators care about is the amount, and form, that ownership is exhibited in. Trust in an API is difficult to earn and can be easily fumbled away.

Ownership of an API translates to the following communication points:

Uptime Dashboard/SLA
Change Log/Release Notes
Roadmaps
Known and Communicated Support and Feedback Channels

Individual instances may vary, but each of these is an attempt to convey stability and permanence — two crucial elements when wooing developers away from other API options. A product with a future and team behind it is orders of magnitude more desirable than unmaintained code deployed on a computer under someone’s desk. A product manager should ensure that the former is being communicated, not the latter.

Usable

There are a variety of different approaches for web-based APIs. Whether using RPC, REST, or subsequent variations, an API design produced by one team may vary significantly in usage and affordances from another team’s product — even when both teams work for the same company! The number of design choices, and how they subsequently manifest in the design, require additional work to ensure usability.

Documentation

This collection of differences means that documentation is incredibly important. In fact, in John Musser’s talk, Ten Reasons Developers Hate Your API, “sucky” documentation was listed as the #1 API problem.

Reasons that documentation may be “sucky” include, but are not limited to:

Being inaccurate/out-of-date/incomplete.
Lacking a getting started onramp.
Unprofessional and/or lacking clarity.

The rise of various formats that capture API intent in structured ways, like the OpenAPI specification, are a start. These integration contracts can be used to render documentation in a manner similar to how annotations in a Java codebase can render Javadoc.

However, like Javadocs, this “documentation” is often the bare minimum that can be done towards effective communication and understanding. An API product manager should be closely involved with the technical writers in the creation of an API’s documentation. They should ensure that the business value of their product is clearly captured to the intended audience.

Standards

A common design consideration is “the principle of least surprise.” Design works best when it reuses familiar interface concepts. With a user interface (UI), this allows end users to make successful educated guesses, resulting in better user experience (UX). Although an API doesn’t have a UI, developers still rely on accumulated experience to shortcut the learning ramp-up necessary for integrators. This developer experience, or “DX” should be part of the consideration when creating an API design.

Common industry patterns for should be used and where possible, data should adhere to standards, and those standards should be explicitly referenced in the documentation. For example, why force a consumer to create their own parsing for your bespoke date and time format? Use ISO8601 instead, reference it in the documentation, and be done with it. Extra points if the API design takes advantage of the work on schema.org and properly uses media types.

Feasible

Different integrations will have different consumptions needs. Some may be able to consume the entire payload as designed. Others, due to computational or bandwidth constraints, may want a refined perspective on the resource available. Working with potential consumers to build in rate controls from the beginning is important.

Malleability

Support for sort ordering and pagination on returned collections is important. Default return amounts, rather than to defaulting to the entire collection, should be explicitly stated in the documentation and modifiable (within reason — page size limits should also be explicitly called out). Filtering, depending on the collection size, may be important. A more advanced option, depending on the need, is to allow for selective parameter retrieval.

Cacheability

APIs should take advantage of the idempotent and safe natures available on the appropriate endpoints. Services enhance cache-ability by setting headers on responses. These headers, at a minimum, should include:

Date
Cache-Control
Expires
Pragma
Last-Modified

It is also possible to use the ETag header for validating the freshness of cached representations, as well as helping with conditional read and update operations. Its value is an arbitrary string for the version of a representation, sometimes a simple hash of the underlying object.

A product manager may not understand the exact technical mechanisms behind how these headers work. However, they should desire the best customer experience possible. For many that means zippy responses. A great resource to get started is Irakli Nadareishvili’s introduction to http caching — How-to: HTTP Caching for RESTful and Hypermedia APIs.

Wrapping Up

If that sounds like a lot to manage, it’s because it is. Being a product manager for an API comes with all the research and testing of a normal product, but with an additional dash of technical acumen and developer savvy. But the reward — easier integrations, more developer happiness, and better expressions of business value — is worth it.