A useful REST API starts with a resource model, not a list of controller methods. Identify the nouns clients need to work with—customers, invoices, projects or documents—and give each resource a stable URI. A collection and one member should have predictable forms, such as /api/v1/projects and /api/v1/projects/{projectId}. Avoid encoding an entire workflow into a verb-heavy URL when the operation can be represented by an HTTP method or a clearly documented action resource.
Model relationships deliberately
Use nested routes when the parent relationship is part of the request context, for example /projects/{projectId}/tasks. Do not nest indefinitely. If a task has its own identity and can be addressed independently, /tasks/{taskId} may be more useful. Decide whether deleting a parent cascades, is restricted, or merely detaches children; document that behavior rather than letting database implementation details define the public contract.
Keep route semantics consistent
Use GET for retrieval, POST for creation or non-idempotent commands, PUT for replacing a representation, PATCH for partial modification and DELETE for removal. A route should not change state merely because a client follows a link or retries a GET request. Keep filtering and sorting in query parameters and validate them against explicit allow-lists.
Example route map
GET /api/v1/projects
POST /api/v1/projects
GET /api/v1/projects/{id}
PATCH /api/v1/projects/{id}
DELETE /api/v1/projects/{id}
GET /api/v1/projects/{id}/tasks
Practical review
For every route, record its resource, method, authentication requirement, authorization rule, request schema, response schema and expected status codes. Check that two routes do not represent the same operation in incompatible ways. Keep internal table names and class names out of the public URL design so the implementation can change without breaking clients.
Further reading
- RFC 9110: HTTP Semantics — https://www.rfc-editor.org/rfc/rfc9110
- MDN: HTTP request methods — https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods