UX Research Methods for API Design

APIs connect machines directly, but the most successful ones are designed for the human enabling the communication.

But far too frequently, API design ends up unintentionally designed by the REST and Hypermedia pieces our frameworks have defined. REST is a great starting point for basic CRUD operations, but it doesn’t adequately explain how to work with collections, relational data, operations that don’t map to basic HTTP verbs, or data extracted from basic resources (such as stats). Hypermedia proponents argue that linked resources best enable discoverability, just as one might browse several linked articles on Wikipedia to learn about a subject. While doing so may help explain resource relationships after enough clicking, it’s not the best way to communicate concepts and it does not help beyond the first stage of software development when developers move to testing and implementation. It also ignores the complexity introduced with nested resource fetching that the consuming developer must manage.

These ideas aren’t bad, but they’re not the only guidance available for designing an API and no single pattern can provide all of the answers. API design should be informed by understanding what developers are looking to accomplish, their assumptions in how they would accomplish a task, their ultimate motivations, and the constraints they manage (business, technical, resource, etc). At a minimum, this requires researching developers themselves, usability testing, and usage data collection. Traditional end-user style research methods don’t directly translate to developers. I will demonstrate how to use these techniques with developers and how to use the knowledge to improve API design. Lastly, I will discuss how to think about the best possible design first, then consider the engineering constraints related to implementation, and how to compromise when necessary. (Hint: it involves accepting that what is hard for you makes you more valuable to your customers.)