REST design checklist · naming, versioning, auth, errors, pagination
Design a REST API your consumers will not curse.
A practical checklist of REST conventions covering resource naming, versioning, authentication, consistent error handling, and pagination. Decide these conventions once, write them down, and every endpoint your team ships will feel like it came from the same API — because it did.
Why API design conventions matter
An API is a contract, and consumers learn it once and expect it to hold. When one endpoint paginates with a cursor and another with page numbers, when errors arrive in three different shapes, or when a field quietly disappears in a release, every integration turns into guesswork and every change generates support tickets. The cost of inconsistency is not paid once — it is paid every day, by every consumer, and by your own future team trying to extend the thing.
This checklist captures the conventions we apply on every API we build. None of it is exotic; it is the boring discipline that separates an API people adopt from one they tolerate. If you want the formal definition of the terms here, the API glossary entry is a quick primer, and the choice between styles is covered in our REST vs GraphQL explainer.
1. Resource naming & structure
- Name resources with plural nouns, not verbs: use /invoices, not /getInvoices. The HTTP method already supplies the verb.
- Map operations to HTTP methods correctly: GET to read, POST to create, PUT or PATCH to update, DELETE to remove. GET requests never change state.
- Express relationships through nesting where it reads naturally, such as /customers/{id}/invoices, but avoid nesting more than two levels deep.
- Use consistent casing for paths and fields, pick one convention for JSON keys, and apply it everywhere without exception.
- Return the right status codes: 200 for success, 201 for created, 204 for no content, 400 for bad input, 401 and 403 for auth, 404 for missing, 409 for conflict, 422 for validation, 429 for rate limits, and 500 for server errors.
- Keep responses predictable: the same resource should serialize the same way whether it is returned alone or inside a list.
2. Versioning
- Choose a versioning strategy before the first external consumer integrates; retrofitting versioning later is painful.
- Prefer a clear scheme — a URL path segment like /v1/ or a version header — and document which one you use and why.
- Never make a breaking change within a version. Adding optional fields is safe; removing or renaming fields, or changing types, is not.
- Publish a deprecation policy: how long old versions are supported, how consumers are warned, and the sunset timeline.
- Maintain a changelog so consumers can see what changed between versions without diffing responses by hand.
3. Authentication & security
- Require authentication on every non-public endpoint, and serve the entire API over HTTPS only.
- Use a standard mechanism — OAuth 2.0 bearer tokens or signed API keys — rather than inventing your own scheme.
- Enforce authorization server-side on every request; never trust a client-supplied role or rely on an unguessable ID for access control.
- Apply rate limiting and return clear 429 responses with headers that tell the consumer their limit, remaining quota, and reset time.
- Validate and sanitize all input, and design with the OWASP API security risks in mind, including broken object-level authorization.
- Scope credentials to least privilege and support rotation, so a leaked key can be revoked without taking down every integration.
4. Error handling
- Return one consistent error shape across the entire API: a machine-readable code, a human-readable message, and where useful, a field-level detail array.
- Make error codes stable and documented so consumers can branch on them programmatically instead of parsing message strings.
- Match the HTTP status to the error category, and never return 200 with an error payload buried inside it.
- Include enough context to debug — what failed and why — without leaking stack traces, internal identifiers, or sensitive data.
- Provide a request or correlation ID in responses so a consumer can quote it when they ask your team for help.
5. Pagination, filtering & sorting
- Paginate every endpoint that returns a collection; an unbounded list is a performance and reliability incident waiting to happen.
- Pick one pagination style — cursor-based for large or frequently changing datasets, offset or page-based for small stable ones — and apply it consistently.
- Return pagination metadata clearly: the next cursor or page, the page size, and where feasible a total count.
- Set a sensible default and maximum page size, and reject requests that exceed the maximum rather than silently truncating.
- Support filtering and sorting with documented query parameters, and keep their naming consistent across endpoints.
How to apply the checklist
Turn this into your team's written API style guide. Decide each convention once — your casing, your versioning scheme, your single error shape, your pagination style — and document the decision so nobody re-litigates it in every pull request. Then enforce it in code review, because conventions that live only in a document drift the moment the team is busy. The goal is that a new endpoint written by a new engineer is indistinguishable from one written a year ago.
Decide the versioning and authentication strategies before your first external consumer integrates; both are painful to retrofit once people depend on you. Pair this checklist with a security review, since the authentication section only scratches the surface of what a real audit covers — our Next.js and Stripe integration guide shows the same error-handling and webhook-verification discipline applied to a payments API in practice.
How this connects to our work
These conventions are the default starting point for every API development engagement we take on, whether we are building a public API for a SaaS product or an internal service that other teams will consume. Good API design is not a separate phase; it is baked into how we structure resources, version safely, and handle errors from the first endpoint. The same discipline shows up in our SaaS platform development and Stripe integration work, where a clean API surface and verified webhooks are non-negotiable.
If you are designing a new API and want a second opinion on the conventions, or you have inherited one that has drifted and needs a cleanup plan, see how we scope and price the work or reach out to talk it through.
Frequently asked questions
Does this checklist apply to GraphQL APIs too?
It is written for REST, which is still the most common style for public and partner APIs. Many principles — consistent errors, authentication, pagination, and versioning discipline — carry over to GraphQL, but the specifics of resource naming and HTTP status codes are REST-oriented.
Why does API consistency matter so much?
Because consumers learn your API once and expect it to behave the same everywhere. If one endpoint paginates with a cursor and another with page numbers, or errors arrive in three different shapes, every integration becomes guesswork. Consistency is the difference between an API people adopt and one they tolerate.
When should I version my API?
Decide on a versioning strategy before your first external consumer integrates, even if you launch at v1 and never bump it for a while. Adding versioning after consumers depend on you is painful. The cheap move is to design for it from day one and only break compatibility behind a new version.
Is good API design really worth the extra effort up front?
Yes. The cost of a poorly designed API is paid every day by every consumer and by your own future team. Inconsistent errors, surprise breaking changes, and missing pagination generate support load and erode trust. A day spent on conventions up front saves months of friction later.
Related resources & reading
SaaS Launch Checklist
The broader pre-launch review your API ships inside of.
Web App Pentest Checklist
Go deeper on the authentication and security section.
Next.js Stripe Integration Guide
Error handling and webhook verification applied to a real payments API.
API Development
How we design and build APIs with these conventions baked in.
Designing or cleaning up an API?
Whether you are starting fresh or untangling an API that drifted, we can help you set conventions, version safely, and ship a surface your consumers trust. See how engagements are priced or book a call.