A REST API is useful when a frontend developer can use it without asking you questions. That means predictable routes, consistent response shapes, and errors that explain what went wrong. Clever features mean nothing if the frontend team cannot guess what a request returns. Design the API from the consumer's side, not from the database's side.
Rules that keep APIs usable
- Use nouns for resources and standard methods for actions, so routes read like sentences.
- Return the same shape for every success and every error, so the frontend handles both with one code path.
- Use proper status codes: missing resources, invalid input, and server errors are different situations.
- Validate input on the server even when the frontend validates too, since requests can come from anywhere.
Document each endpoint with one example request and response. If you cannot write the example, the endpoint is not ready.