The API design mistake that haunts every version

My first public API was a mirror of my database tables. It felt efficient at the time — the objects came straight from the ORM, fields and all. It took about three months to understand the trap: now the database couldn't change without breaking the API, and the API couldn't change without breaking clients. The internal detail had become a public contract.

What I do instead now

Design responses around what the client needs, not what the table stores. A "post" response includes the author's display name — not a user ID the client must resolve with a second call.

Version from day one. /v1/ in the path feels premature until the first breaking change, when it's the only thing standing between you and angry users.

Deprecate with a paper trail. New fields get added; old fields get marked, documented, and given a sunset date. Silent removal is how you teach people not to trust you.

Never expose what you can't take back. If a field might change meaning — don't ship it. Internal IDs, internal flags, internal status enums: all of them harden into permanence the moment someone builds on them.

The principle

An API is a promise, and promises should be about the domain — users, orders, posts — never about your storage choices. The database is an implementation detail. The moment clients can see it, they own it.