REST API Design Best Practices in Express

REST API Design Best Practices in Express

REST design is a skill. Bad API design is hard to fix once clients depend on it. Here are the best practices.

1. Use Nouns, Not Verbs in Paths

/users, not /getUsers. /users/:id, not /getUserById. The HTTP method is the verb.

2. Plural Nouns for Collections

/users for the collection, /users/:id for one user. Consistent. Plural is the convention.

3. Use the Right HTTP Method

• GET: read.
• POST: create.
• PUT: replace.
• PATCH: partial update.
• DELETE: remove.

4. Status Codes

• 200: OK (GET, PATCH).
• 201: Created (POST).
• 204: No Content (DELETE).
• 400: Bad Request.
• 401: Not authenticated.
• 403: Not authorized.
• 404: Not Found.
• 409: Conflict.
• 422: Unprocessable entity.
• 500: Server error.

5. Consistent Response Shapes

{ "data": { ... }, "error": null }

Or just return the resource on success and an error object on failure. Pick one and stick to it across all endpoints.

6. Pagination for Collections

/users?skip=0&limit=20. Return next link or cursor. Never return the entire collection without a limit.

7. Version APIs

/api/v1/users. Bump the version when you make breaking changes. Old clients keep using v1; new clients use v2.

8. Filter, Sort, and Select via Query

/users?role=admin&sortBy=createdAt&fields=name,email. Let clients ask for what they need without custom endpoints.

9. Nest Resources When They Belong Together

/users/:userId/posts for posts of a user. But do not nest more than one level deep. If deeper, use /posts/:id directly with a filter.

10. Use OAuth or JWT for Auth

Bearer token in Authorization header or JWT in httpOnly cookie. Do not put API keys in URL params.

11. Validate Input

Use zod or express-validator. Reject invalid bodies with 400 and a list of errors. Validate at the boundary, before any logic runs.

12. Use HATEOAS Optionally

For hypermedia APIs, include links to related resources. Most teams skip this and use documented contracts instead.

The Takeaway

Good REST API design: nouns in paths (plural for collections), right HTTP methods, correct status codes, consistent response shapes, pagination for collections, versioning (v1), filtering and sorting via query, shallow nesting, JWT or OAuth auth, and input validation. Bad design is hard to fix later.