List vs Single Object Response in Spring REST — Design and ResponseEntity

Direct Answer

A collection endpoint can return a JSON array, a page envelope, or another documented collection representation. A single-resource endpoint returns one representation or an explicit absence response. Returning Optional<T> directly is not a portable promise of automatic 404 handling; map absence to ResponseEntity or a handled exception. Pagination should be based on expected size and use case, not an absolute rule that every list must be paged.

Code Example

@RestController
@RequestMapping("/api/users")
public class UserController {
    private final UserRepository userRepository;

    // Single object - return Optional, handle 404
    @GetMapping("/{id}")
    public ResponseEntity<User> getUserById(@PathVariable Long id) {
        return userRepository.findById(id)
            .map(ResponseEntity::ok)  // 200 with user if found
            .orElse(ResponseEntity.notFound().build());  // 404 if missing
    }

    // Collection - paginated by default
    @GetMapping
    public Page<User> getAllUsers(Pageable pageable) {
        return userRepository.findAll(pageable);  // Spring handles serialization
    }

    // Search - also paginated
    @GetMapping("/search")
    public Page<User> searchUsers(@RequestParam String name, Pageable pageable) {
        return userRepository.findByNameContaining(name, pageable);
    }
}

Common Mistakes & Pitfalls

• No Pagination on List Endpoints: The classic fresher mistake is @GetMapping returning List<User> from findAll() with no Pageable. It works perfectly in local testing with your 10 seed users. You deploy to staging with 5,000 users and the endpoint takes 3 seconds. Production has 200,000 users and it crashes with OutOfMemoryError. Always paginate collection endpoints from day one.
• Returning Optional from Collection Endpoints: Some freshers return Optional<List<User>> thinking it handles the empty case. Wrong pattern. An empty list is a valid result—just return the empty list. Optional is for single-item endpoints where absence is meaningful.
• Not Using ResponseEntity for Single Items: Returning User directly from findById means you can't handle the not-found case gracefully. The method would have to throw an exception for 404, which is messy. Returning Optional and mapping to ResponseEntity is cleaner and gives you proper HTTP semantics.