Apps, websites, ERPs and partner integrations all talk through APIs. When an API is well designed, new clients integrate in hours. When it is poorly designed, every integration becomes a project full of exceptions. That is why following rest api best practices is an investment that pays off quickly.
In this article, we gather the most important conventions, with practical examples.
What is a REST API
REST, or Representational State Transfer, is an architectural style defined by Roy Fielding in 2000. A REST API exposes resources, such as customers, orders and products, through URLs. It then uses HTTP verbs to operate on them. In most cases, data travels as JSON.
1. Use plural nouns for resources
The URL identifies the resource. The action is expressed by the HTTP verb. See the difference:
- Avoid:
/getCustomers,/createOrder - Prefer:
/customers,/orders,/orders/42/items
2. Use HTTP verbs correctly
- GET: reads data without changing anything.
- POST: creates a new resource.
- PUT: replaces an entire resource.
- PATCH: updates only some fields.
- DELETE: removes a resource.
In addition, GET, PUT and DELETE should be idempotent. In other words, repeating the same request produces the same result.
3. Return the right status codes
- 200 OK for success and 201 Created after creating a resource.
- 204 No Content when there is no response body.
- 400 Bad Request and 422 Unprocessable Entity for invalid data.
- 401 Unauthorized without authentication and 403 Forbidden without permission.
- 404 Not Found when the resource does not exist.
- 429 Too Many Requests when the rate limit is exceeded.
- 500 only for unexpected server errors.
Returning 200 with an error message in the body confuses clients and monitoring tools.
4. Standardize error messages
Every error response should share the same format, with a code, a readable message and field-level details. RFC 9457, known as Problem Details, is a good reference.
5. Version from day one
Breaking changes will happen. To avoid breaking existing integrations, include the version in the URL, such as /v1/orders, or in a header. This way, you can ship v2 without affecting clients still on the previous version.
6. Paginate, filter and sort lists
Never return every record at once. Use parameters such as ?page=2&per_page=50, filters such as ?status=paid and sorting such as ?sort=-created_at. For large volumes, cursor-based pagination is more efficient than page numbers.
7. Secure the API
- Always use HTTPS.
- Authenticate with tokens, such as OAuth 2.0 or expiring access tokens.
- Check permissions on every resource to prevent IDOR flaws, where a user accesses someone else's data just by changing an ID.
- Apply rate limits per client.
- Validate every input and never expose internal details in error messages.
8. Document with OpenAPI
An undocumented API is a hard-to-use API. The OpenAPI specification lets you generate interactive documentation, examples and even client libraries automatically. Include real request and response examples for every endpoint.
Frequently asked questions
REST or GraphQL?
REST is simple, takes advantage of HTTP caching and covers most use cases. GraphQL helps when many different clients need varied combinations of data.
What is the difference between PUT and PATCH?
PUT replaces the entire resource. PATCH changes only the fields you send.
Conclusion: REST API best practices pay off
Following REST API best practices makes your API predictable: well-named resources, correct verbs, consistent status codes, versioning and clear documentation. These practices cut integration time and prevent security flaws. If your company needs to build or integrate APIs, count on WDS Developer.