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.)
Jeremiah Lee claims that UX is empathy as an applied science and that APIs are the new division of labor. With his pioneering work in both user experience design and software engineering, he has promoted the idea of developer experience through UX Magazine, SXSW Interactive, and the APIdays international conference series. He’s currently helping to make the world a healthier, happier place as an API engineer at Fitbit.
For exhibition and sponsorship opportunities, contact Sharon Cordesse at scordesse@oreilly.com
For information on trade opportunities with O'Reilly conferences, email partners@oreilly.com
For media-related inquiries, contact Maureen Jennings at maureen@oreilly.com
View a complete list of Fluent contacts