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.

There was a time when Jan Koum, a quiet engineer working at Yahoo, applied for a job at Facebook.

He was rejected.

But as with many great entrepreneurial stories, that wasn’t the end.

He moved on.

The very next year, he bought an iPhone—and in that moment, he saw what most people didn’t: the App Store was going to change everything.

He gathered a handful of former Yahoo colleagues to build something deceptively simple—an instant messenger to replace expensive SMS.

They called it WhatsApp.

By the time Facebook came knocking again, WhatsApp had become the fastest-growing messaging app in the world, signing up 1 million users every single day.

At its peak before acquisition, WhatsApp was delivering 50 billion messages daily to 450 million active users—with a team of just 32 engineers.

This wasn’t an accident. It was a masterclass in engineering discipline, smart technology choices, and relentless focus.

Let’s break down how they did it.

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.