Quick answer: A well designed REST API is predictable. It uses nouns for resource URLs, standard HTTP methods for actions, meaningful status codes, consistent JSON responses, clear error messages, pagination for large lists, versioning from day one, and honest documentation. If a developer can guess how an endpoint works after using two others, you have designed it well.
APIs are how modern software talks to other software. Your mobile app, your partners and your own website may all depend on the same API. A clumsy API slows every one of those projects down. These are the principles we follow when designing APIs for clients.
If you are new to the idea, start with our guide on what an API is, then come back here.
What REST means in practice
REST is an architectural style described by Roy Fielding in his doctoral dissertation in 2000. In everyday use, a “REST API” usually means an API that:
- Exposes resources, such as customers, orders or products, at their own URLs
- Uses HTTP methods like GET, POST, PUT and DELETE to act on them
- Sends and receives data in a standard format, usually JSON
- Is stateless, so each request contains everything the server needs
You do not need to follow every academic rule to build a good API. You do need to be consistent.
1. Design URLs around resources
URLs should name things, not actions. Use plural nouns and keep the structure shallow.
Good:
- GET /customers
- GET /customers/42
- GET /customers/42/orders
Avoid:
- GET /getCustomer?id=42
- POST /createNewOrder
Keep URLs lowercase, use hyphens between words if needed, and do not expose internal details such as database table names or file extensions.
2. Use HTTP methods for what they mean
Each method has a well understood purpose:
- GET reads data and never changes anything
- POST creates a new resource
- PUT replaces a resource completely
- PATCH updates part of a resource
- DELETE removes a resource
Following these meanings lets developers, caches and tools make safe assumptions. A GET request that deletes data is a bug waiting to happen.
3. Return the right status codes
Status codes tell the client what happened before it reads the body. Use the common ones correctly:
- 200 OK for a successful read or update
- 201 Created when a POST creates something, with a Location header pointing to it
- 204 No Content for a successful delete
- 400 Bad Request when the input is invalid
- 401 Unauthorized when authentication is missing or wrong
- 403 Forbidden when the user is known but not allowed
- 404 Not Found when the resource does not exist
- 409 Conflict for clashes such as duplicate records
- 429 Too Many Requests when a rate limit is hit
- 500 Internal Server Error when something breaks on your side
Never return 200 with an error message hidden in the body. It breaks error handling for everyone.
4. Make responses consistent
Pick conventions and stick to them across every endpoint:
- One naming style for fields, such as snake_case or camelCase
- One date format, ideally ISO 8601 with time zones
- The same structure for single items and for lists
- IDs always returned as the same type
Small inconsistencies cost integrators hours of debugging.
5. Write helpful error messages
A good error response has a machine readable code and a human readable message. For validation errors, say which field failed and why. For example, return a code such as “invalid_email”, a message saying the email address is not valid, and the field name. Developers should be able to fix their request without contacting you.
6. Paginate, filter and sort large collections
Returning ten thousand orders in one response is slow for everyone. Support:
- Pagination with page and per_page parameters, or a cursor for large or fast changing data sets
- Filtering with query parameters, such as /orders?status=paid
- Sorting with a parameter such as sort=created_at
Include pagination details in the response, such as total count or a link to the next page, so clients know when to stop.
7. Version your API from the start
Your API will change. Versioning lets you improve it without breaking existing apps. The simplest approach is putting the version in the URL, such as /v1/customers. Some teams prefer a version header. Either works if you are consistent.
When you retire an old version, announce it well in advance. Twitter’s shutdown of its old API version in 2013 is a good reminder of how disruptive an abrupt change can be for developers who depend on you.
8. Secure it properly
- Serve everything over HTTPS, without exceptions
- Use token based authentication. OAuth 2.0 is the common standard for letting third party apps act on a user’s behalf. Simple API keys can be fine for server to server use
- Check permissions on every request, not just at login
- Apply rate limits to protect the service from abuse and runaway scripts
- Never put secrets or personal data in URLs, since URLs end up in logs
9. Support caching where it helps
For data that does not change often, use HTTP caching headers such as ETag and Cache-Control. Clients can then skip downloading data they already have, which makes your API faster and cheaper to run.
10. Document it like a product
Documentation is part of the API, not an afterthought. Good docs include:
- An overview of authentication and how to get credentials
- Every endpoint with its parameters, example requests and example responses
- All error codes and what to do about them
- A changelog
Tools such as Swagger can generate interactive documentation from a specification file, which helps keep docs and code in step. A sandbox environment where developers can test safely is a big bonus.
A quick design checklist
Before you release an endpoint, ask:
- Is the URL a noun, and does it match the others?
- Does the HTTP method match what the endpoint does?
- Are the status codes correct for success and every failure case?
- Is the response format consistent with the rest of the API?
- Is it paginated if it returns a list?
- Is it documented with a working example?
FAQ
Is REST better than SOAP?
For most web and mobile projects, REST with JSON is simpler and faster to work with. SOAP still appears in enterprise and financial systems where its strict contracts are useful.
Should every API be public?
No. Many APIs are private and power a company’s own website and apps. The same design principles still apply, because your own developers are users too.
How do I handle breaking changes?
Release them in a new version, keep the old version running for an agreed period, and give users clear notice and migration notes.
Need an API built or reviewed?
We design and build APIs that connect websites, apps and business systems, and we review existing APIs for consistency and security. See our approach to custom development.
