The Heroku HTTP API Design Guide, revisited

Jun 5, 2021

One of our most influential late Heroku artifacts was The Heroku HTTP API Design Guide. We’d recently revamped our API with a new V3 iteration, and the guide was a terse description of the conventions we’d developed. It was written by Mark McGranaghan, and then entered common maintenance.

It blew up when it was dropped, accumulating 13.5k stars on GitHub, and translated into a number of foreign languages. It was a big deal for us at the time because we hadn’t managed to produce all that much on the thought leadership 1 front since the company’s halcyon days of ~2011.

The project was eventually converted to GitBook format, which was a little unfortunate because it lost its original succinctness. I’ve created a fork of the project to bring it back to its more easily digestible original state.

Reading back through it today, it stands up pretty well. There are a few suggestions that were put forward without enough convincing rationale (e.g. use of V4 UUIDs, which I was partly complicit in proposing), but it’s not a huge problem. One of my strongest beliefs when it comes to API design is that it’s most important to establish some convention, because without any, things start drifting all over the place very quickly. A perfectly reasonable approach would be to copy a lot of the guide, change the sections you disagree with, and then adopt that for internal guidance.

The guide’s most important non-obvious innovation is its brevity. It’s written in simple, candid language that makes the entire thing easy to consume in just a few minutes. At Stripe (as a counterexample), we had at least one document that attempted to state design principles, but it was lengthy and unfocused, which made it rarely referenced in practice. Having something in the form of a written artifact was good, but it was pretty uninspiring to read.

This came to mind recently because I’m looking at writing something similar for use at Crunchy, and I’m currently looking copying out large parts of the Heroku guide for reuse. More on this as the project gets further along.

1 This term used ironically.

Did I make a mistake? Please consider sending a pull request.