When your team sets out to build an API, it’s tempting to jump straight into writing code. But most APIs fail not because they lack fancy technology, but because they are confusing, inconsistent, or hard to maintain.
In this post, I’ll walk you through a practical approach to designing a REST API that actually works—clear to understand, easy to evolve, and a delight for developers to consume.
It was a Saturday afternoon, sometime back in 2020.
A notification popped up in my email:
"Our production systems are down."
I quickly opened my laptop, started digging through the logs, and discovered that our API gateway had crashed.
The sales team was breathing down our necks—they had just launched a huge promotional campaign for the courses we sell on our edtech platform.
Users were dropping fast.
I quickly removed the API gateway from our stack and ran the application without rate limits.
The issue was resolved—at least for the moment.
My team took a deep breath, as if we had just avoided some kind of tsunami.