“The handles of a craftman’s tools bespeak an absolute simplicity, the plainest forms affording the greatest range of possibilitites for the user’s hand.
“That which is overdesigned, too highly specific, anticipates outcome; the anticipation of the outcomes guarantees, if not failure, the absence of grace.” - William Gibson, All Tomorrow’s Parties
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. This 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 Eriksson defines the Product Manager role as an expertise that lies at the intersection of tech, business, and UX. Martin then 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 audience that will consume the API. That may be harder than it sounds, as there are several different types of people evaluating an API, each with their own questions. 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, make it easy for an integrator to fix?
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 system 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 part of ownership 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 frittered away.
Ownership of an API translates to the following communication:
- Uptime Dashboard/SLA
- Change Log/Release Notes
- Roadmaps
- Known and Communicated Support and Feedback Channels
The individual forms by which each manifest may vary. However, each of these attempts to convey stability and permanence; two crucial elements when wooing developers with other 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 the designs are usable.
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 suck include, but are not limited to:
- Being inaccurate/out-of-date/incomplete
- Lacking a getting started onramp
- Unprofessional and/or lacking clarity
Formats that capture an API’s intent, 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 in creating an API’s documentation. They should ensure that the business value of their product is clearly captured and expressed 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 (or UI), this allows end users to successfully make educated guesses. This results in better user experience (UX). A corollary developer experience, or “DX”, should be part of the consideration when creating an API design.
Common industry patterns should be used. Where possible, data should adhere standards, and those standards should be explicitly referenced in the documentation. For example, why force a consumer to parse your bespoke date 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, 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 exactly technical mechanisms behind how these headers work. However, they should desire the best customer experience possible, and - for many - that means zippy responses.
Phil Sturgeon has a couple of fantastic pieces on HTTP caching. The first is a blog post on how to speed up API performance with HTTP response caching. The second is a presentation he recently gave that was posted to YouTube.
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.
