REST API design seems simple until you have maintained an API that was designed carelessly. Inconsistent naming conventions, URLs that reflect database tables rather than resources, error responses that differ by endpoint, versioning strategies bolted on after the fact โ these are the kind of problems that create friction for every developer who consumes or maintains the API for its lifetime. Getting the design right at the start costs relatively little and pays off consistently.
Resource-Oriented URL Design
URLs should identify resources, not operations. The resource is the noun; the HTTP method is the verb. /users/42 identifies a specific user; GET /users/42 retrieves it, PATCH /users/42 updates it, DELETE /users/42 removes it. /users/42/posts identifies the collection of posts belonging to that user. This is a REST URL; /getUser?id=42 or /deleteUser/42 are RPC patterns that discard the HTTP method’s semantics.
Plural nouns for collections (/users, /posts, /orders), singular nouns for single resources (/users/42), lowercase kebab-case for multi-word names (/service-categories), and no verbs in the path are the consistent conventions that make an API predictable to consume without consulting documentation for every endpoint.
HTTP Status Codes: Precision Matters
Returning 200 OK with an error object in the body is a common mistake that forces API consumers to parse every response body to determine success or failure, rather than using HTTP status codes for that purpose. Use 201 Created for successful POST requests that created a resource. Use 204 No Content for successful DELETE operations. Use 400 Bad Request for client-side validation failures; 401 for unauthenticated requests; 403 for authenticated but unauthorised requests; 404 for resources that do not exist; 422 for semantically invalid requests that pass validation; 409 for conflicts such as duplicate resource creation; and 500 for server-side errors.
Consistent Error Response Format
Define an error response format and use it consistently across every endpoint. A minimal format includes a machine-readable error code, a human-readable message, and optionally a details array for validation errors that lists the specific fields with their specific issues. Consistent error format means API consumers write error handling once and it works for all endpoints, rather than writing bespoke parsing logic for each endpoint’s idiosyncratic error structure.
Versioning Strategy
API versioning is a trade-off between consumer stability and API evolution. URL versioning (/api/v1/users) is the most explicit and the easiest to manage in logs and documentation. Header versioning is more RESTfully pure but harder to test in a browser and less visible in monitoring. For most internal and partner APIs, URL versioning is the practical choice. Maintaining v1 while developing v2 is additional overhead, but it prevents breaking changes from affecting consumers that have not yet migrated.
Middleware Architecture in Express
Express’s middleware chain provides a clean mechanism for cross-cutting concerns: authentication, rate limiting, request logging, input sanitisation, error handling. Each concern should be its own middleware function, applied globally or to specific route groups. Error-handling middleware (four-argument functions with err as the first parameter) should be registered after all other middleware and routes to catch unhandled errors and return consistent error responses rather than Express’s default HTML error pages.