REST API Design: Best Practices and Common Mistakes
Design APIs that developers love. Learn REST conventions, error handling, versioning, and documentation strategies.

The first list endpoint I shipped returned a bare JSON array. It was fine for a few months. Then the table grew past a couple of hundred thousand rows and the endpoint started timing out, so we needed pagination. But there was nowhere to put a "next page" pointer in a bare array. Turning the response into an object was a breaking change, and every mobile client that had already shipped to users broke on release day.
Almost every painful API change I have seen started with a design decision that felt too small to think about: a response shape, an error format, a missing idempotency guard. This post covers the decisions to make before the first client depends on you. Versioning and authentication get their own deep dives, which I link below.
Quick takeaways
- Model resources as nouns, let HTTP methods carry the verb, and keep URLs boring and predictable.
- Wrap list responses in an object (
datapluspage) from day one, and prefer cursor pagination for large tables. - Return errors in one machine-readable shape (RFC 9457 problem details) with a stable
typeclients can switch on. - Make unsafe operations retry-safe with an
Idempotency-Keyheader. - Document with OpenAPI and include real request and response examples for every endpoint.
How should I name resources and use HTTP methods?
Use plural nouns for collections and put identifiers in the path. The method says what happens:
GET /orders list orders (filter, sort, paginate)
POST /orders create an order
GET /orders/{id} read one order
PATCH /orders/{id} partial update
PUT /orders/{id} replace the whole resource
DELETE /orders/{id} remove it
GET /orders/{id}/items sub-resource, one level of nesting at most
POST /orders/{id}/cancel an action that is not plain CRUD
GET /getOrders repeats what the method already says. Reserve verbs for actions that do not fit CRUD, like cancel, and model them as POST to a sub-path. Keep nesting shallow; past two levels, give the child its own top-level route with a filter.
Which status codes should an API return?
Use the code that tells a client what to do next, not just whether it worked:
- 200 for a successful read or update, 201 for a creation (with a
Locationheader), 204 when there is nothing to return. - 400 for a malformed request, 422 for a well-formed request that fails validation.
- 401 when the caller is not authenticated, 403 when they are authenticated but not allowed.
- 404 for a missing resource, 409 for a conflict, such as a duplicate or a stale update.
- 429 when rate limited, with a
Retry-Afterheader. - 500 only for failures that are genuinely yours.
Never return 200 with an error inside the body. Clients, proxies and monitoring tools all trust the status line.
How do I paginate list endpoints?
Offset pagination (?page=500) gets slower as the offset grows and skips or repeats rows when data changes between requests. Cursor (keyset) pagination avoids both. Return an opaque cursor that encodes the last row seen:
{
"data": [{ "id": 1042, "status": "paid" }],
"page": { "has_more": true, "next_cursor": "eyJpZCI6MTA0Mn0" }
}
const encodeCursor = (id: number) => Buffer.from(JSON.stringify({ id })).toString("base64url");
const decodeCursor = (cursor: string): number => JSON.parse(Buffer.from(cursor, "base64url").toString()).id;
app.get("/orders", async (req, res) => {
const limit = Math.min(Number(req.query.limit) || 20, 100);
const after = req.query.cursor ? decodeCursor(String(req.query.cursor)) : null;
const { rows } = await db.query(
`SELECT id, status FROM orders
WHERE ($1::bigint IS NULL OR id < $1)
ORDER BY id DESC
LIMIT $2`,
[after, limit + 1], // fetch one extra row to know if there is a next page
);
const hasMore = rows.length > limit;
const data = rows.slice(0, limit);
res.json({
data,
page: { has_more: hasMore, next_cursor: hasMore ? encodeCursor(data[data.length - 1].id) : null },
});
});
Always cap limit, and return 400 for a cursor that does not decode. The ordering column needs an index, otherwise the query is no better than offset.
What should error responses look like?
Pick one shape and use it everywhere. RFC 9457 "problem details" is a standard, so client libraries already understand it:
{
"type": "https://api.example.com/problems/validation-error",
"title": "Validation failed",
"status": 422,
"detail": "One field is invalid.",
"errors": [{ "field": "quantity", "message": "must be at least 1" }]
}
Send it with Content-Type: application/problem+json. The important field is type: it is a stable identifier that clients can branch on, whereas the human-readable title and detail can change freely. Write messages that help a developer fix the call, and never include stack traces or internal table names. The server-side half of this, deciding what to expose and what to log, is covered in error handling patterns.
How do I make POST requests safe to retry?
Networks fail after the server has done the work. A client that retries a payment request without protection charges the customer twice. Ask clients to send a unique Idempotency-Key and store the first response under it:
app.post("/payments", async (req, res) => {
const key = req.header("Idempotency-Key");
if (!key) {
return res.status(400).type("application/problem+json").json({
type: "about:blank",
title: "Missing Idempotency-Key header",
status: 400,
});
}
const saved = await store.get(key);
if (saved) return res.status(saved.status).json(saved.body); // replay, do not charge again
const result = await createPayment(req.body);
await store.set(key, { status: 201, body: result }, 24 * 3600);
res.status(201).json(result);
});
In production, claim the key atomically before doing the work (for example with Redis SET NX), so two simultaneous retries cannot both pass the check.
Where do versioning, authentication and documentation fit?
Decide your versioning rules before the first release; API versioning strategies that don't break clients covers what counts as a breaking change, and catching breaking changes in CI with OpenAPI diff and Pact shows how to enforce it. For authentication, API keys suit server-to-server calls, JWTs suit stateless clients, and OAuth 2.0 is for third-party access; the trade-offs are laid out in authentication patterns: session, JWT and OAuth.
Document with an OpenAPI file that lives next to the code, and include a real example request and response for each endpoint. Examples are what developers copy first.
Which API design mistakes cause the most support tickets?
- No HTTPS. Encrypt everything in production, no exceptions.
- Returning too much. Serializing a database row directly leaks fields like password hashes and internal flags. Map to explicit response types.
- No rate limiting. One buggy client loop can take down everyone. Return
429withRetry-After. - Poor error messages. "Bad request" with no detail turns a one-minute fix into a support thread.
- Inconsistent shapes. Some lists wrapped, others bare; some errors
message, otherserror. Consistency is most of what "good API design" means.
What should I do this week?
Open your busiest list endpoint and check three things: is the response an object with room to grow, does it paginate with a capped limit, and do its errors use one documented shape? Fix the first one now, while the change is still cheap, and write the problem-details helper once so every handler reuses it. Then export your OpenAPI file and add one real example to the three endpoints your clients call most.
Uğur Kaval
AI/ML Engineer & Full Stack Developer specializing in building innovative solutions with modern technologies. Passionate about automation, machine learning, and web development.


