An API's contract — its resource names, pagination shape, and error format — is the only interface most developers will ever touch, so it deserves the same deliberate design attention as a screen. Treat naming, consistency, and error handling as UX decisions, not implementation afterthoughts, and developer trust follows. Treat them as afterthoughts, and it doesn't.
Quick answer: An API's naming, pagination, error shapes, and idempotency rules are UX surfaces, not backend plumbing — they are the only part of your product a developer directly experiences. Design them contract-first, hold every choice to the principle of least astonishment, and review the finished contract with real consumers before writing implementation code.
Your API's Ergonomics Are UX Decisions Wearing a Trench Coat
Resource naming, pagination style, error shapes, and idempotency rules are not neutral engineering choices — they are the felt experience of using your API, exactly like a button label or an error toast is the felt experience of using an app. A platform PM who skips this design layer ships a worse product, even with a flawless backend underneath it.
Most PMs would never approve a checkout flow with three different date formats across three screens. Yet plenty of APIs mix snake_case and camelCase field names between endpoints, paginate one resource by offset and another by cursor, and return an HTTP 200 with the real error buried inside the body. Each inconsistency is a small tax a developer pays on every integration.
The stakes are higher than with a typical UI, too. Developers can read your source, inspect your headers, and switch to a competitor's SDK in an afternoon — there's no loyalty premium for a familiar layout.
A few of the decisions that quietly function as UX:
- Resource naming — whether
/ordersreads as an obvious noun or forces a developer to guess between/order,/Orders, and/getOrders. - Pagination style — whether a consumer can trust a
nextcursor or has to defensively re-derive offsets after every write. - Error shapes — whether a failed request tells a developer exactly what to fix or hands them a stack trace to reverse-engineer.
- Idempotency — whether retrying a timed-out request is safe or silently double-charges a customer.
This is the same argument behind treating developer experience as the product's front door: if the API is the front door, its contract is the door handle, the sign above it, and the lock, all at once. Get any one of those wrong and the rest of the product's quality barely registers.
Jobs-to-be-done thinking makes the stakes concrete. A developer doesn't call your API for its own sake — they hire it to fetch a record, trigger a workflow, or reconcile a payment, and every friction point in the contract is friction against that job getting done. It's the same lens the Jobs to Be Done framework applies to any other product decision, just pointed at a developer instead of an end user.
Jakob Nielsen's consistency and standards heuristic — one of the ten usability heuristics Nielsen Norman Group has taught interface designers since 1994 — applies just as cleanly to a JSON payload as to a button. Don't make users, or developers, wonder whether different words, situations, or actions mean the same thing across your surface.
Contract-First Design and the Principle of Least Astonishment
Contract-first design means writing the API's shape — an OpenAPI or JSON:API specification, endpoint by endpoint — before any implementation code exists, so consumers can react to the interface while it's still cheap to change. The principle of least astonishment says every design choice should match what a reasonable developer already expects, based on the rest of your API and the wider ecosystem.
Roy Fielding's 2000 doctoral dissertation, the paper that coined the term REST, wasn't really an argument about JSON over HTTP. It argued that a set of interface constraints — statelessness, uniform resource identification, cacheability — makes a system more predictable to every client that touches it, regardless of who built the client.
Modern contract-first tooling chases the same goal with better ergonomics:
OpenAPIdocuments every endpoint's shape in one machine-readable file, before a handler exists.JSON:APIstandardizes how resources, relationships, and errors are represented, so consumers don't relearn conventions per endpoint.- Public style guides, like Zalando's open-sourced RESTful API guidelines, turn tribal team knowledge into a checklist anyone can review against.
The point of all three is the same: the hard conversations — what's a resource, what's nested, what's a query parameter versus a path segment — happen on a spec, not in a pull-request review of already-finished code.
The principle of least astonishment predates REST. It shows up in Unix design lore, documented in Eric Raymond's The Art of Unix Programming as the "Rule of Least Surprise," and it reduces to one test: if a developer who already knows the rest of your API guesses how a new endpoint behaves, are they right?
Least astonishment is violated the moment two endpoints in the same API answer the same kind of question in two different shapes — one returning
nullfor "not found," the other returning an empty array.
Contract-first design is also a stance on who the API is for. Treating API consumers — whether they sit on another team internally or at a partner company — as real customers with real expectations is the same argument made in treating your platform as a product for internal customers. That stance is what makes a PM insist on a design review before a sprint starts, not after a partner complains.
A Walkthrough: Designing a Clean Resource Model
A clean resource model names things as nouns, keeps nesting to one level wherever possible, is consistent about casing and pluralization, and puts everything a consumer needs to reason about state — status, timestamps, links to related resources — directly on the resource. Here's how that plays out designing an orders API from a blank page.
1. Start with nouns, not verbs. The path names the thing; the HTTP method names the action. GET /orders and POST /orders, never /getOrders or /create-order — the verb already lives in the method, so repeating it in the path is redundant and, worse, sometimes contradicts it.
2. Cap nesting at one level. /customers/{id}/orders is fine — it reads as "this customer's orders." /customers/{id}/orders/{orderId}/items/{itemId}/refunds forces every consumer to carry four IDs around just to issue a refund. Prefer a flatter /refunds/{id}, with orderId and customerId as fields inside the resource, not segments in the path.
3. Pick one casing convention and defend it forever. camelCase or snake_case in JSON bodies — either is fine, but mixing them across endpoints means every SDK generator and every new hire has to special-case your API instead of trusting a rule.
4. Version once, deliberately. A URI-based version (/v1/orders) is visible and cache-friendly; a header-based version is cleaner URLs but invisible in logs and browser history. Pick one, document the deprecation policy alongside it, and don't let a second scheme creep in later.
5. Make pagination cursor-based for anything unbounded. Offset pagination looks simpler to build, but it silently skips or repeats rows the moment a write happens between two page requests — exactly the kind of failure a developer discovers in production, not in a demo.
| Pattern | Example | Why it works or fails |
|---|---|---|
| Noun-only path | GET /orders/{id} | Method carries the verb; path stays stable across actions |
| Verb-in-path | GET /getOrderById/{id} | Redundant with the method; breaks convention the moment someone adds /fetchOrder next to it |
| Single-level nesting | /customers/{id}/orders | Reads as ownership; easy to guess without documentation |
| Deep nesting | /customers/{id}/orders/{oid}/items/{iid}/refunds | Forces four IDs per call; nearly impossible to guess correctly unaided |
| Consistent casing | customerId everywhere | One rule, zero special cases in generated SDKs |
| Mixed casing | customer_id here, customerId there | Every consumer writes defensive mapping code |
Map that whole sequence — discovery, first successful call, first error, first production incident — onto an emotion curve the way the customer journey framework maps any adoption arc. The resource model's real job is to keep that curve from dipping hard at "first error" and "first production incident," because those are the moments developers decide whether to trust your API with anything bigger.
Error Design: A Well-Shaped Response vs. a Hostile One
A well-shaped error response gives a developer a stable machine-readable code, a human-readable message, and enough context — which field, which constraint — to fix the problem without opening a support ticket. A hostile one returns a raw stack trace, a bare 500, or a 200 status with the real failure buried three levels deep in the body.
Here's the same failure — a missing required field — handled two ways.
Hostile:
HTTP/1.1 200 OK
{
"success": false,
"error": "Error"
}
The status code itself lies here; this was not a success. The message names nothing a developer can act on, and there's no code to branch logic on programmatically.
Well-shaped:
HTTP/1.1 422 Unprocessable Entity
{
"error": {
"type": "invalid_request_error",
"code": "parameter_missing",
"message": "The `customer_id` parameter is required.",
"param": "customer_id",
"doc_url": "https://api.example.com/docs/errors#parameter_missing"
}
}
This version — close to the pattern Stripe's public API reference documents for its own error objects — gives a developer four things at once: an accurate status code, a stable code to branch on, a specific param, and a link straight to the relevant documentation.
| Dimension | Hostile response | Well-shaped response |
|---|---|---|
| Status code accuracy | 200 on failure | 4xx/5xx matches the real outcome |
| Machine-readable code | Absent or free text | Stable code string, safe to branch on |
| Field-level detail | None | Names the exact param at fault |
| Human message | Generic ("Error") | Specific, actionable sentence |
| Documentation link | None | doc_url pointing at the relevant page |
| Consistency | Shape differs per endpoint | One error envelope, reused everywhere |
Postman's annual State of the API report has, across multiple survey cycles, found that unclear documentation and inconsistent error handling rank among developers' most-cited frustrations with third-party APIs — typically named by a clear majority of respondents, well ahead of complaints about missing functionality. Developers forgive a small feature gap far more easily than they forgive a contract that lies to them about what just happened.
Pagination, Idempotency, and the Decisions That Compound
Idempotency keys and predictable pagination are small mechanical details that determine whether a retrying client corrupts data or safely no-ops, and whether a consumer can page through ten records or ten million without missing rows during concurrent writes. Both are cheap to get right at design time and expensive to retrofit once real traffic depends on them.
Idempotency means a client can safely retry a request — after a timeout, a dropped connection, a flaky mobile network — without risking a duplicate side effect. The now-common pattern, documented in Stripe's public API reference, attaches a client-generated Idempotency-Key header to any request that creates or mutates state:
- First request with a given key: executes normally, stores the result.
- Retried request with the same key: returns the stored result again, without re-executing the side effect.
- A request with a new key: treated as a genuinely new operation.
Pagination has a similar cheap-now-or-expensive-later shape:
| Approach | Behavior under concurrent writes | Typical use |
|---|---|---|
Offset (?page=2&limit=50) | Can skip or repeat rows when records are inserted mid-page | Small, rarely-changing lists |
Cursor (?after=cursor_abc) | Stable regardless of concurrent inserts or deletes | Anything unbounded, high-write, or customer-facing |
None of this shows up on a roadmap slide, which is exactly why it's easy to underfund. It's the same dynamic covered in funding the invisible platform work no one asks for: idempotency handling and cursor pagination don't have a demo, but their absence eventually shows up as a P1 incident involving a customer's finance team and a duplicated charge.
Review the Contract Before You Write a Line of Code
The cheapest time to catch a bad resource name, a missing error field, or an inconsistent pagination style is before any handler code exists — once a contract ships to even one external consumer, every fix becomes a breaking-change negotiation instead of an edit. Review the spec itself, with the people who will actually call it, as its own deliverable.
A workable review pass:
- Share the draft spec — endpoints, auth, request and response payloads — before writing implementation code.
- Walk a real or representative consumer through the happy path and at least one error path, out loud.
- Ask them to guess the next endpoint's shape from the ones already reviewed; if they guess wrong, you've found an astonishment violation.
- Get explicit sign-off on naming, pagination style, and the error envelope before implementation starts, not after.
This is the exact gap Prodinja's API Designing tool is built to close. You define each endpoint — method, path, auth, request and response payloads — and it turns that definition into a shareable curl command and a rendered spec artifact, giving you a concrete contract to walk a consumer through before a single line of implementation code ships.
Contract review is one habit among several that separate platform PMs who ship durable interfaces from those who ship whatever engineering happened to build first. For the fuller picture of the role this sits inside, see the complete guide to the platform PM role.
Key Takeaways
- Your contract is your UX. Naming, pagination, error shapes, and idempotency are the felt experience of your API — design them with the same intent as a screen.
- Contract-first design front-loads the hard conversations. An
OpenAPIorJSON:APIspec lets consumers react before implementation makes a fix expensive. - The principle of least astonishment is a design test, not a slogan. If a developer who knows the rest of your API guesses wrong about a new endpoint, you've violated it.
- A resource model should stay flat, noun-based, and consistently cased. Depth, verbs in paths, and mixed casing are the three most common self-inflicted wounds.
- Error responses need a stable machine-readable code, a specific field, and a doc link — not just an accurate-sounding message.
- Idempotency and cursor pagination are cheap now and expensive later. Fund them before the incident that forces the retrofit.
- Review the spec itself with real consumers before a line of code ships. It's the single highest-leverage moment to fix a contract problem.
Frequently Asked Questions
What does "API as a product" mean?
It means treating your API's contract — not just its underlying service — as something with real users who have expectations, workflows, and switching costs. Naming, consistency, documentation, and error handling get the same product rigor a customer-facing screen would get, because for a developer, the contract is the screen.
What is contract-first API design?
Contract-first design means specifying an API's endpoints, payloads, and error shapes — typically in OpenAPI or JSON:API — before any implementation code is written. Consumers, and even mock servers, can react to the contract while changes are still nearly free, instead of after a working backend has calcified the design.
What is the principle of least astonishment in API design?
It's the rule that any new part of an interface should behave the way someone familiar with the rest of it would already expect. In API terms: if a developer who knows your other endpoints guesses how a new one paginates, errors, or names its fields, they should guess correctly.
How should I design error responses for an API?
Return an accurate HTTP status code, a stable machine-readable code string a client can branch on, a specific human-readable message naming the exact field or constraint at fault, and — where possible — a link to relevant documentation. Reuse the same error envelope shape across every endpoint.
Should I version my API in the URL or in a header?
Either works if applied consistently; URI versioning (/v1/orders) is more visible in logs, caches, and support tickets, while header-based versioning keeps URLs clean but hides the version from anyone not inspecting requests directly. The failure mode isn't which you pick — it's picking one and later letting a second scheme creep in alongside it.