The 10 API Commandments

Once a consumer depends on a field, renaming it breaks their app. Once they parse your error format, changing it breaks their error handling. Your API is a published interface with downstream dependencies — not internal code you can refactor freely.

// Renamed without warning — mobile app crashes
{ "user_name": "alice" }

// Old field kept, new field added
{ "userName": "alice", "user_name": "alice" }

Your API serves developers, not your ORM. When your API mirrors your database schema, every schema migration becomes an API breaking change. Model around what consumers need, not how you store it.

POST /api/sendEmail
POST /api/createUser
GET /api/getOrderById?id=123

POST /api/emails
POST /api/users
GET /api/orders/123

Every HTTP client, monitoring tool, retry logic, and cache relies on status codes. When you return 200 for errors, you break all of them. Consumers have to parse your body to know if the request succeeded — that's a bug, not a design choice.

HTTP/1.1 200 OK

{"status": "error", "message": "User not found"}

HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{"type": "/errors/not-found", "title": "Not Found", "status": 404}

Inconsistency is the #1 source of developer frustration. When userId is camelCase in one endpoint and user_id in another, every consumer has to handle both. Automate consistency with linting so you don't argue about it in code reviews.

{"userId": "u_1", "created_at": 1681380000, "OrderStatus": "active"}

{"user_id": "u_1", "created_at": "2026-04-13T10:00:00Z", "order_status": "active"}

Adding pagination later is a breaking change. Offset pagination breaks when items are inserted and gets slower at scale. Cursor pagination is stable, O(1), and works from the start. Return _links so the frontend never builds pagination URLs.

{"data": ["...all 12,000 items..."]}

{"data": ["...20 items..."], "_links": {"next": {"href": "/api/tasks?page[after]=abc123"}}, "meta": {"has_next_page": true}}

Networks fail. Clients retry. If your POST endpoint creates a new resource every time it's called, a single network timeout can cause a double charge. Idempotency keys let the server recognize duplicate requests and return the cached result instead of re-processing.

POST /api/payments
// Client retries after timeout -> two charges

POST /api/payments
Idempotency-Key: pay_req_abc123
// Server returns cached result on retry -> one charge

The OWASP API Top 10 exists because most APIs ship with the same vulnerabilities: broken object-level authorization, excessive data exposure, missing rate limiting on login endpoints. Your API key identifies the caller — it doesn't prove who they are. Secrets in URLs end up in server logs, browser history, and CDN caches.

GET /api/users/123?api_key=sk_live_REDACTED

GET /api/users/123
Authorization: Bearer eyJhbG...
X-API-Key: pk_live_app_id

99 requests at 50ms + 1 request at 5000ms = average of 99ms. Looks fine. But that p99 user — who hits your API 100 times per session — has a 63% chance of experiencing the 5-second response. Averages hide your worst performance from your best customers.

Stripe didn't win because they had the best payment API. They won because they had the best documentation. If a developer can't get a 200 response in 5 minutes with your docs, they'll find an API where they can. Write the spec first (OpenAPI), include curl examples for every endpoint, show error responses — not just the happy path.

Every API version you maintain is a version you support, document, test, and eventually sunset. If you design for evolution — additive fields, optional parameters, Postel's Law — you'll version once every few years instead of every release. When you must deprecate, use Sunset headers and migration guides, not surprise removals.