Chapter 01: Introduction

It’s been more than two decades since the dawn of the Web 2.0 era, which marked a major turning point in the development of web services. At the beginning of the new millennium, the world was already equipped with a number of web standards created in response to the growing interest in the public internet. But with the rise of interactive web applications and the evolution of JavaScript, there was increasing pressure to build simpler and more flexible web services. In response to this need, REST APIs gradually emerged as the natural solution.

Even though the principles of REST have been around for over twenty years, developers still don’t agree on what a well-designed REST API should actually look like.

I started working with REST API design back in 2015. For my first project, I aimed to follow the existing standards and conventions as strictly as possible. Although there was no shortage of resources available, most of them contradicted each other in key areas. It wasn’t until I gained real-world experience that I was able to find my own approach to designing effective REST APIs.

In 2019, I became an independent freelance professional. Corporate training has always been a core part of my service offering. After several iterations of my technical training on Developing REST APIs, I realized that awareness of API design in the Czech Republic was surprisingly poor. That same year, I added a dedicated REST API Design course to my portfolio.

Since 2020, I’ve been continuously refining this training based on feedback from participants. The course is highly interactive and covers many controversial topics that often challenge developers’ assumptions about how web services should be designed. In addition to established standards, modern REST APIs are largely shaped by conventions.

API design needs to be approached in a broader context. That’s the only way to build a web service based on rules that work together in synergy rather than contradicting each other. 

To make this topic accessible not only to companies but also to individual developers, I decided to compile everything I’ve learned about REST API design into the guide you’re reading now. It contains the practical know-how that will help you design REST services you can be proud of.

Bringing this guide to life took several hundred hours, and it reflects insights gained from a decade of real-world projects. In early 2025, I fully revised the original Czech content and rewrote it in English to share it with the rest of the world.

How to Read This Guide?

I’ve structured the content so that the chapters build on each other. That’s why I recommend reading at least the first 19 chapters in order. The later chapters are more of thematic extensions. Throughout the guide, you’ll also occasionally find links to additional articles that dive deeper into specific topics.

Although my primary goal in this guide was to focus on best practices, I also chose to highlight some examples of poor design decisions. That’s why you’ll occasionally come across color-coded markers that indicate:

🟢 recommended solution — best practice
🟠 acceptable solution with caveats
🔴 not recommended — poor practice

Foundations

I believe it’s important to emphasize that this guide adheres to all widely recognized standards. In many cases, my recommendations are even stricter, as the official standards often lean toward leniency for the sake of backward compatibility. The conventions in this guide are based not only on my own experience, but also on proven patterns from many modern APIs I’ve worked with as a developer. It’s this role, on the integrating side, that has allowed me to identify many of the weak spots where API design commonly fails.

hope you’ll appreciate the effort behind this work and that it brings you both insight and inspiration.

Miroslav Holec
Your API Design Guide