RESTful URL Design with Path Variables — Best Practices
Fast recall
Quick revision
Core answer
Understanding of REST principles and URL design conventions — shows thinking beyond just Spring annotations
Using verbs in URLs like /getUser or /deleteOrder — REST uses HTTP methods for actions, not URL verbs
Show the complete CRUD URL design for a resource hierarchy with proper HTTP methods and nested resources
Interview-ready guide
Interview answer
GET /users/42 reads a user representation; DELETE /users/42 requests deletion. GET /users/42/orders lists that user's orders. GET /orders/900 may be clearer for an order with a global id. Including both user and order ids does not prove order 900 belongs to user 42; the service must verify that relationship and the caller's permission.
RESTful URL Design with Path Variables — Best Practices
Direct Answer
Resource-oriented paths usually use nouns, stable identifiers, and HTTP methods for protocol actions. Nest paths when the child is meaningfully scoped by its parent, but do not mirror every database relationship or assume nesting improves security. Authorization must verify ownership regardless of URL shape, and deeply nested paths can become brittle.
Code Example
@RestController
@RequestMapping("/api/users")
public class UserController {
private final UserService userService;
@GetMapping
public List<User> getAllUsers() {
return userService.findAll();
}
@GetMapping("/{userId}")
public User getUserById(@PathVariable Long userId) {
return userService.findById(userId).orElseThrow();
}
@PostMapping
public User createUser(@RequestBody User user) {
return userService.save(user);
}
@PutMapping("/{userId}")
public User updateUser(@PathVariable Long userId, @RequestBody User user) {
return userService.update(userId, user);
}
@DeleteMapping("/{userId}")
public void deleteUser(@PathVariable Long userId) {
userService.delete(userId);
}
@GetMapping("/{userId}/orders")
public List<Order> getUserOrders(@PathVariable Long userId) {
return userService.findOrdersByUserId(userId); // nested resource
}
@GetMapping("/{userId}/orders/{orderId}")
public Order getUserOrder(@PathVariable Long userId, @PathVariable Long orderId) {
return userService.findOrder(userId, orderId); // two-level hierarchy
}
}
Common Mistakes & Pitfalls
- Using verbs in URLs: Writing
/createUseror/getOrderDetailsviolates REST principles. The HTTP method is the verb — usePOST /usersandGET /orders/{id}instead. Freshers often copy SOAP or RPC patterns where actions are in the URL. - Mixing path variables with verbs: Creating URLs like
/users/{userId}/deletewhen it should beDELETE /users/{userId}. The HTTP method already expresses the action. - Flat URLs for hierarchical data: Using
/orders/{orderId}when orders belong to users. The URL/users/{userId}/orders/{orderId}better expresses the domain relationship and allows proper access control checks (does this order belong to this user?).
Check your understanding
Answer these without looking back at the article.
- Why is /getUsers a bad RESTful URL?
- How deep should URL nesting go in REST API design?
- How do you represent filtering in a REST URL?
Looking for a structured roadmap?
Every module on this page is also part of the full Java backend interview track.