Introduction

I’ve designed a lot of web APIs in my career. The details—data, language, business—always change, but the work is largely the same. When it’s really good, we spend approximately 0% of our time focusing on what the API looks like and 100% of our time focusing on what the API enables.

I’ve finally taken some time to write all this down, because with every new project I find myself repeating the same ideas. I hope this serves as inspiration for you, but also I hope it serves as a shorthand for me.

I hope that this guide will help you accomplish the same thing. It’s a set of practical and pragmatic strategies based on real experience that prioritizes the goals of your user and mitigates development risk. Soon, you’ll be implementing predictable and pleasant APIs very quickly, and everyone will be happy, and life will probably be just great.

If you’re reading this right now because we’re about to build an API together and I asked you to take a look, thank you very much for your time.

If you find errors, please email me; I’d really appreciate it. If you disagree with me on subjective points, you can also email me about those, but I’ll appreciate it a little less.