Your API is Public Infrastructure: Design for the Clueless Developer

When you build an internal API, you can just tell your coworker how it works. When you build a public API, your documentation and design choices are the only things preventing mass frustration.

Good API design is not about what is easy for you to write—it is about what is impossible for the consumer to break.

1. Stop Using Generic 400 Bad Request Errors

Telling a developer their request is "Bad" without explaining why is a massive waste of time.

• The Fix: Return explicit, structured error payloads. Tell the consumer exactly which field failed, why it failed (e.g., "must be a valid email"), and provide a documentation URL directly in the error response body.

2. Idempotency is Not Optional

Network requests fail, causing clients to retry. If a retried billing request charges a customer twice, your API is broken.

• The Fix: Support Idempotency-Key headers on all mutating (POST/PATCH) requests. Save the initial response in a fast cache like Redis. If the same key hits your server again, return the cached result instead of executing the logic twice.

3. Version in the URL or the Headers? Pick One and Stick to It

Breaking changes ruin developer trust. If you change a data type or remove a field, you must version your API.

• The Fix: Whether you prefer path versioning (/v1/users) or header versioning (Accept: v2), implement it globally. Never introduce silent, breaking changes to a live production endpoint.

The Bottom Line

An API is a binding contract between your backend and the outside world. Design it defensively, document it flawlessly, and treat your API consumers like your most important users.

Let me know if you would like to adjust this by providing:

• A specific industry context (e.g., fintech, e-commerce, or SaaS)
• A sample error payload code block to include
• Your target platform (e.g., Twitter/X thread, LinkedIn, or Dev.to)