Scalable API design is mostly about making early decisions you can live with: stable resource names, predictable pagination, consistent errors, a clear versioning rule and documentation that stays current. Get those right and an API can grow from one internal consumer to many partners without constant breakage or rewrites.
Scalable API design starts with treating the API as a promise
The moment another system depends on your API, you have made a promise: this URL, this field and this behaviour will keep working. Business systems make this promise stricter than most. An accounting export, a warehouse integration or a partner portal may run unattended for years, and nobody is watching when it breaks on a Tuesday night.
Before designing endpoints, write down three things: who the consumers are (your own web front end, a mobile app, a customer's system), how much control you have over them, and what a breaking change would cost them. If you control every consumer and can deploy them together, you have freedom. If a customer's IT supplier maintains the other side, you do not, and the design should be more conservative.
Scale here means more than traffic. It also means more consumers, more developers touching the code, and more years of accumulated decisions. A design is maintainable when a new developer can predict how an endpoint behaves before reading its code.
Resource design and naming
Most business APIs are well served by a resource-oriented style: nouns in the URL, standard HTTP methods for the action. Whether you call it REST or just a consistent HTTP API matters less than being consistent.
- Use plural nouns for collections.
/customersand/customers/42, not/getCustomer. - Let the method carry the verb. GET reads, POST creates, PUT or PATCH changes, DELETE removes. Reads must never change data.
- Nest only one level.
/customers/42/ordersis readable; five levels of nesting is a maintenance burden. Give deeply nested things their own top-level route. - Model business actions explicitly. Not everything is create, read, update or delete. Something like cancelling an order is often clearer as
POST /orders/42/cancellationthan as a status field someone edits freely. - Keep naming boring and uniform. Pick one case style for fields, one date format (ISO 8601 with a time zone is the safe choice) and one way to represent money, ideally an amount in the smallest unit plus a currency code.
Return only what the consumer needs, and never expose your database structure directly. If a table column is renamed next year, the API should not have to change with it.
REST or GraphQL?
For most business systems with a handful of known consumers, a plain HTTP API is simpler to cache, secure, monitor and document. GraphQL earns its complexity when many different clients need very different slices of the same data and you want them to shape their own queries. It is a trade-off, not an upgrade, and it brings its own concerns such as query cost limits.
Pagination, filtering and limits
Any endpoint that returns a list will eventually return a list that is too big. Add pagination from day one, because adding it later changes the response shape and breaks consumers.
| Approach | How it works | Best for | Watch out for |
|---|---|---|---|
| Offset and limit | Skip N records, return M | Small datasets, admin screens with page numbers | Slow on deep pages; records can shift between requests |
| Cursor (keyset) | Return records after an opaque marker | Large or fast-changing data, sync jobs | No jumping to page 17; needs a stable sort order |
Whichever you choose, set a sensible default page size and a hard maximum so one careless request cannot pull an entire table. Always define a stable sort order, otherwise pages can repeat or skip records. Return enough in the response for the caller to continue, such as the next cursor or a link to the next page.
Filtering and sorting should use documented, whitelisted parameters. Do not pass raw query fragments through to the database. Add rate limits too, and return a clear signal when a caller exceeds them so well-behaved clients can back off instead of retrying in a loop.
Errors that help the caller
When an integration fails at night, the error message is the only support the developer gets. Treat errors as part of the product.
- Use HTTP status codes honestly: 400-range for problems the caller can fix, 500-range for problems on your side. Do not return success with an error inside the body.
- Use one error shape everywhere: a machine-readable code, a human-readable message, and for validation problems the list of offending fields.
- Include a request identifier in every response and log it on your side, so a caller can quote it and you can find the exact request.
- Do not leak internals. Stack traces and SQL fragments help attackers, not callers. Detail on API security belongs in its own review; our article on secure API development for SaaS products covers where to start.
Versioning without breaking clients
Versioning is the rule that lets you change your mind. The most useful habit is to separate changes that are safe from changes that are not.
Usually safe (additive)
Adding a new optional field to a response, adding a new endpoint, or adding an optional request parameter. Tell consumers in your documentation that they must ignore fields they do not recognise; this one sentence prevents many incidents.
Breaking
Removing or renaming a field, changing a type, making an optional parameter required, changing the meaning of a value, or tightening validation. These need a new version.
The common mechanisms are a version in the path (/v2/orders), a version in a header, or a date-based version pinned per client. Path versioning is the easiest for consumers to understand and test in a browser or a simple tool, which is why it is a sound default for business APIs. Whatever you choose, keep the number of live versions small, because every version you run is code you must test, patch and secure. If you build in PHP, our guide to designing a REST API in PHP shows how routing and structure support this, and the .NET API practices article covers the same ground for that stack.
Documentation and examples
An API without documentation is a guess. Aim for a machine-readable description, such as an OpenAPI file, that is generated from or tested against the real code so it cannot quietly drift. Around it, write the parts a specification cannot carry:
- A quick start that gets a first successful call working in minutes, including how to obtain credentials in a test environment.
- Real request and response examples for every endpoint, including at least one error example.
- The rules that are not obvious: rate limits, pagination behaviour, idempotency, how time zones and currencies are handled.
- A changelog that states what changed, in which version, and what consumers must do.
Offer a sandbox with fake data so partners can test without touching production. This reduces support questions and makes onboarding a new integration partner far less painful.
Monitoring and deprecation
You cannot maintain what you cannot see. Log every request with the caller identity, endpoint, status, duration and request identifier. Watch error rates and slow endpoints per consumer, not only in aggregate; one broken integration can hide inside healthy overall numbers. Alert on patterns such as a sudden rise in authentication failures or a consumer that has gone quiet.
Monitoring also tells you who still uses an old version, which is what makes deprecation humane. A workable deprecation process looks like this:
- Announce the change in the changelog and by direct message to known consumers, with a retirement date set far enough ahead for their release cycles.
- Mark deprecated endpoints in the documentation and, where practical, in response headers.
- Contact consumers that are still calling the old version as the date approaches.
- Retire only when usage has dropped, and keep a plan for a short extension if an important consumer is not ready.
Putting it together
If you are starting an API now, a short design review pays off: agree naming rules, pagination style, the error format and the versioning policy on one page before writing endpoints. If you already have an API, pick the weakest of those four areas and fix it first, usually errors or documentation, because they cost the least and help every consumer immediately. When the API connects systems such as ERP and CRM, read how to approach integrating ERP, CRM and web systems with APIs next. If you want a second pair of eyes on a design, our software development for Danish companies page explains how we work remotely with teams.
Frequently asked questions
How do I version a REST API?
Keep changes additive wherever possible, and introduce a new version only for breaking changes such as removed fields or changed meanings. A version in the path, like /v2/orders, is the simplest for consumers to understand. Document each version, announce retirement dates well ahead, and keep the number of live versions small.
How should pagination work?
Add pagination from the start with a default page size and a hard maximum. Offset and limit suit small datasets and admin screens; cursor-based pagination suits large or fast-changing data. Use a stable sort order, and return what the caller needs to fetch the next page, such as a cursor or link.
Should I use REST or GraphQL?
For most business systems with a few known consumers, a plain resource-oriented HTTP API is simpler to cache, secure and document. GraphQL helps when many clients need different slices of the same data and want to shape their own queries, but it adds complexity such as query cost control. Choose based on consumers, not fashion.