A colleague asked me if I had a good reading list for API design, since that’s part of my job these days. I did quite a bit of reading before I dug into doing design work, but never collected the best resources in one place. Until now! So, here are texts I’ve read that I would recommend familiarity with before setting out to design an HTTP API.
RESTful Best Practices
Todd Fredrich’s book RESTful Best Practices is a concise, free book filled with useful guidelines. You’ll never get complete agreement on lots of API design issues, but if you’re just getting started, this book will certainly set you on the right path. I agree with most everything in this book.
HTTP API Design
An even more compact resource is the HTTP API Design repository. It covers much of the same ground that Todd Fredrich’s book does, but also includes more technical peripheral recommendations, like using TLS and passing version information via the Accept header.
Steve Klabnik’s Nobody Understands REST or HTTP
In a passionate blog post, Steve Klabnick gets back to basics to explain why so many APIs succumb to basic mistakes that were so clearly outlined correctly in Fielding’s dissertation. He’s come back to many of the points in subsequent posts and revisions, so it’s worth reading. He’s given these topics a lot of thought.
RESTful Web Services
A somewhat dated book from 2007, RESTful Web Services covers the basics of RESTful design, and is now available in its entirety under a Creative Commons license. It was written in a time where SOAP was all the rage, and was thus championing the virtues of a stateless server implementation. One of the ways it shows its age is by focusing on XML as the primary interchange format, though JSON is discussed to a fair degree. Never mind that, though, the fundamentals are all there, and for the most part, still sound.
RESTful Web APIs
A 2013 follow-up to RESTful Web Services, RESTful Web APIs picks up where the Web Services left off, delving deeply into the details of HATEOAS. While HATEOAS is an important concept, many aspects of it may not be suitable for some use cases. Web APIs is a great read because it explores some of those nuances, although it is perhaps not necessary for those just getting started on API design.
Thoughts on RESTful API Design
Geert Jansen’s Thoughts on RESTful API Design is a well-written, relatively detailed overview of good API design guidelines. It covers a bit of theory, but it is predominantly focused on the real practicalities of API design, like how HTTP verbs should be used, pagination, and how to design a solid URL structure.
Perhaps I’ll put together a discussion of some of the API design challenges I’ve faced. There are many practical challenges beyond the basics covered in these resources that are worth looking at, like how to design an API for multiple products that utilize the same information, when to inline one resource inside another, and how to design for both high-performance and bandwidth-constrained clients.