What are good URL naming conventions for REST resources?
SHORT ANSWER
Use plural nouns for resources, let the HTTP method express the action, nest only one level for relationships, and use lowercase with hyphens. So GET /students/5/courses, not /getStudentCourses?id=5.
Explain it simply
A REST URL names a thing, not an action. The verb comes from the HTTP method. Think of a library: the shelf label says "Books", and what you do (borrow, return, add) is the request you make at the desk.
| Goal | Poor | Better |
|---|---|---|
| List students | GET /getAllStudents | GET /students |
| One student | GET /student?id=5 | GET /students/5 |
| Create | POST /createStudent | POST /students |
| Update | POST /updateStudent/5 | PATCH /students/5 |
| Delete | GET /deleteStudent/5 | DELETE /students/5 |
| A student's courses | GET /studentCourses/5 | GET /students/5/courses |
Example
js
router.get("/students", listStudents);
router.post("/students", createStudent);
router.get("/students/:id", getStudent);
router.patch("/students/:id", updateStudent);
router.delete("/students/:id", deleteStudent);
router.get("/students/:id/courses", listStudentCourses);Guidelines:
- Plural nouns:
/students, not/student. - Lowercase and hyphens:
/exam-results, not/ExamResults. - Do not nest deeply.
/students/5/courses/9/lessons/3is hard to maintain; after one or two levels use/lessons/3. - Filters go in the query string:
/students?branch=cse. - For real actions that are not CRUD, a sub-resource verb is acceptable:
POST /orders/12/cancel.
What to say in the interview
"Resources are plural nouns, the HTTP method is the verb, relationships nest one level, and filters go in the query string. This makes the API predictable without reading the docs."
Common mistakes
- Putting verbs in URLs and using GET for deletions.
- Mixing singular and plural names across endpoints.