Preface

APIs are everywhere, yet many of us have learned to design them through trial and error, often more error than we’d care to admit. RESTful API Design Patterns and Best Practices was born from our collective “aha moments” and, frankly, our mistakes while working with teams across different organizations. We noticed that most API design resources fall into two camps: highly technical guides that assume you’re building in a vacuum, or business-focused books that gloss over the nitty-gritty details. The reality? Great API design happens at the intersection of both worlds.

Between the two of us, we’ve run API initiatives at companies like Adidas, Backmarket, ING, and PZU; watched countless teams struggle with the same challenges; and celebrated when they finally clicked with the right approach. What became clear is that there’s a sweet spot between technical excellence and business value, and that’s exactly where this book aims. Plus, with AI systems getting chattier and more dependent on well-crafted APIs, the bar for good API design just got higher.

Think of this book as your guided tour through three distinct territories. Part 1: The Apprentice’s Study is where we get comfortable with the fundamentals—why APIs exist, how to think about them as products, and how to apply domain thinking that actually makes sense. Part 2: The Wizard’s Grimoire is where we roll up our sleeves and dive deep into REST design, comparing different approaches and building solid foundations. Part 3: The Archmage’s Circle is where we get practical with OpenAPI, JSON Schema, hypermedia, and keeping your APIs healthy as they evolve.

While you could jump around the book like a choose-your-own-adventure novel, we’ve structured it with some method to our madness. The Domain-Driven Design chapters in Part 1 build on each other, and the technical chapters in Part 3 are definitely better as a progression. Trust us on this one; we’ve seen what happens when teams skip the foundation work.

To keep things practical, we follow a “Magic Items store” through Chapters 9–12. This isn’t just academic theory; these patterns come from real projects, real deadlines, and real conversations with development teams who needed solutions yesterday.

Here’s the thing: we’re at a fascinating moment where traditional API design meets AI-driven interactions. The APIs you design today need to work for both human developers debugging at 2 a.m. and AI agents that might consume your endpoints in ways you never imagined. This book gives you the tools to build for both audiences without losing your sanity.

Whether you’re designing your first API or you’re the person everyone turns to when things get complicated, we hope this book becomes the resource you wish you’d had when you started, practical, comprehensive, and maybe even a little fun.

Andrzej Jarzyna & Samir Amzani