Endpoint Empathy: Designing APIs Developers Won't Curse in Six Months
Photo: developer reading API documentation with JSON response on screen, via bairesdev.mo.cloudinary.net
There's a moment every API consumer remembers: the first time they hit an endpoint and it does exactly what the docs said it would. It's a small thing. It's also the difference between an integration that takes an afternoon and one that eats a week of somebody's sprint.
Internal APIs have users too. They just happen to sit in the next Slack channel instead of a public support queue, which makes it easier to forget they're customers at all.
Your users write code against you
Frontend engineers, mobile devs, partner teams, and that script in the data pipeline nobody documents — they all program against the contract you publish. When the contract is inconsistent, they build workarounds. When it's ambiguous, they guess. When it breaks without warning, they lose a day and file a ticket that says 'API weird' with no additional context.
Designing for those people means optimizing for two things: time to first successful request, and time to diagnose a failure at 2am when the on-call engineer has never seen your endpoint before.
Consistency beats cleverness every single time
Every API team eventually writes a style guide, and the specifics matter far less than the fact that you have one and follow it. Pick these once and stop debating:
- Resource names are plural nouns.
/users,/invoices,/shipping-labels. Not/getUser, not/user-list. - Pick one case for JSON fields and never mix. Most US teams land on
snake_case. Whatever you choose,user_idandcreatedAtcannot both appear in the same payload. - Timestamps are ISO 8601 in UTC.
2026-11-13T14:22:07Z. No epoch seconds in one field and a formatted local string in another. - IDs are strings in the payload, even if they're integers in the database. This saves you the day you migrate to a UUID and every client's type definition explodes.
- Actions that aren't CRUD get an explicit sub-resource, like
POST /invoices/{id}/void— not a?action=voidquery parameter.
None of this is exciting. All of it is what makes an API feel like it was designed by someone who expected other people to use it.
Error payloads are your documentation under pressure
A bad error response is the most expensive thing you can ship. It converts a five-minute fix into a support thread. Some ground rules:
- Never return 200 with an error in the body. Ever.
- Use status codes honestly. 400 for malformed requests, 401 for missing or bad credentials, 403 for authenticated-but-not-allowed, 404 for missing resources, 409 for conflicts, 422 for semantically invalid data, 429 for rate limits. Don't collapse everything into 400 because routing was easier.
- Include a stable machine-readable code that clients can branch on, separate from the human message.
code: "invoice_already_paid"will outlive three rewrites of the human text. - Point at the field. If validation failed on
billing_address.zip, say so, with the offending value if it isn't sensitive. - Return a request ID and log it server-side. This one field turns support conversations from archaeology into a lookup.
- Say whether it's retryable, and if it is, include a
Retry-Afterheader.
Something like:
{
"error": {
"code": "payment_method_declined",
"message": "The card was declined by the issuer.",
"field": "payment_method.token",
"retryable": false,
"request_id": "req_8f2c1a94b3"
}
}
That payload answers the three questions every integration hits: what broke, where, and what do I do next.
Pagination: pick a pattern and commit
Offset pagination is easy to build and easy to explain, and it breaks the moment records are inserted mid-scroll. Cursor pagination is stable under writes and slightly more work for clients.
For anything that grows — feeds, logs, events, transaction history — use cursors. Return an opaque next_cursor the client passes back verbatim, plus a has_more boolean. Don't make clients construct cursors from field values; that turns an implementation detail into a contract.
Whatever you choose:
- Cap
limitwith a documented maximum (100 or 200 is typical) and a documented default. - Wrap the list in an envelope —
{ "data": [...], "next_cursor": "...", "has_more": true }— so you can add metadata later without breaking every client. - Be honest about
total_count. Counting rows on a large table is expensive. Either don't offer it or offer it as an explicit opt-in parameter with a documented cost.
Versioning is a tradeoff, not a religion
URL path versioning (/v1/invoices) is the least elegant option and the easiest for everyone to understand. Header-based versioning is cleaner in theory and a nightmare in every debugging session where someone forgets to set the header and gets a confusing 404.
For most teams, path versioning wins on operational simplicity, and that's a legitimate reason to choose it. The more important rule is this: most changes don't need a version bump at all.
- Adding a new optional field to a response: safe.
- Adding a new optional request parameter: safe.
- Adding a new endpoint: safe.
- Renaming a field, changing a type, making an optional field required, removing an enum value: breaking, and it needs a real migration plan.
When you do break something, deprecate loudly. Announce a date, emit a Deprecation and Sunset header so automated clients can see it, keep the old shape running long enough that people actually migrate, and publish a changelog humans can read.
Docs that answer the questions people actually ask
The fastest way to find the gaps in your documentation is to read your own support channel for a week. It'll be the same five questions. Put the answers in the docs:
- A copy-pasteable
curlexample with real (sandbox) credentials for every endpoint - Full request and response bodies for every documented error case, not just the happy path
- How authentication and token refresh actually work, including what happens on expiry mid-request
- Rate limit behavior, including the headers that tell a client how much budget remains
- Idempotency key support for anything that moves money or creates a resource
- Webhook retry semantics, signature verification, and ordering guarantees
- A sandbox environment with data that doesn't require a support ticket to obtain
If you generate an OpenAPI spec, keep it accurate — a stale spec is worse than no spec, because it makes people trust something that's lying to them.
The pre-flight checklist
Run this before the first endpoint ships, and again before you call an API stable:
- Every resource is a plural noun and every field follows one casing convention.
- Every timestamp is ISO 8601 UTC, and every ID is a string.
- Every error returns a proper status code, a stable code string, and a request ID.
- Every list endpoint has a documented limit cap, default, and pagination envelope.
- Nothing in the initial design requires a version bump to extend later.
- The docs contain at least one complete example for every error a developer will realistically hit.
- Rate limits are documented with headers a client can read programmatically.
- There's a sandbox, and it works without a sales call.
APIs are the longest-lived code most teams write. The endpoint you sketch on a Tuesday afternoon will still be serving traffic when the framework under it has been rewritten twice. It's worth ten extra minutes of design up front — and worth treating the people on the other end of the HTTP call as the users they are.