Spring REST

What is an API, and What Makes it REST?

An API (Application Programming Interface) is a contract that defines how two pieces of software communicate. In the web world, it means: "send me an HTTP request in this exact shape, and I'll send back a response in this exact shape." The API is the boundary — your Java code is invisible behind it, and the client (a browser, a mobile app, another backend service) only ever sees the contract.

Before REST existed, most APIs used SOAP — a protocol built on XML envelopes with rigid structure, its own error format, and a WSDL contract file. SOAP worked, but it was verbose, brittle, and painful to consume. In 2000, Roy Fielding's PhD dissertation described REST (Representational State Transfer) — not a protocol, but a set of architectural constraints for designing networked systems using what HTTP already provides. REST won because it maps naturally to HTTP, returns data in formats clients already understand (JSON, XML), and requires no special libraries to consume.

A RESTful API organises everything around resources (nouns, not verbs — /users, not /getUsers), uses standard HTTP verbs to express what operation to perform on those resources, and is stateless — each request carries all the context the server needs; no server-side session remembers who you are between calls. This is what makes REST APIs scalable: any server instance can handle any request, with no sticky sessions required.

/*
 *  WITHOUT REST (RPC-style, pre-2000 approach):
 *
 *  POST /getUserById        POST /createNewUser
 *  POST /updateUserEmail    POST /deleteUserAccount
 *  POST /getAllActiveUsers   POST /searchUsersByName
 *
 *  The verb is in the URL — every operation needs its own endpoint.
 *
 *  WITH REST (resource + HTTP verb):
 *
 *  GET    /users         → list users
 *  POST   /users         → create a user
 *  GET    /users/123     → get user 123
 *  PUT    /users/123     → replace user 123
 *  PATCH  /users/123     → partially update user 123
 *  DELETE /users/123     → delete user 123
 *
 *  One resource URL, six operations — the verb is the HTTP method, not the URL.
 */

What This Page Covers

REST principles in depth are in RESTful API Principles. Spring's request routing mechanics are in Spring MVC. This page focuses on the full stack of building a production-grade REST API in Spring: DTOs, validation, correct HTTP semantics, error responses, versioning, and calling other services.

DTOs — Never Expose JPA Entities in Your API

This is the most common architectural mistake in Spring REST APIs: returning the JPA @Entity directly from the controller. The entity is a database mapping — it may contain password hashes, internal audit fields, lazy-loaded collections that trigger N+1 queries during JSON serialisation, or bidirectional relationships that cause infinite recursion in Jackson. A DTO is what the API contract says it is, independent of how the database stores it.

// The JPA entity — internal, never the API contract
@Entity @Table(name = "users")
public class User {
    @Id @GeneratedValue(strategy = GenerationType.IDENTITY) private Long id;
    private String name;
    private String email;
    private String passwordHash;     // NEVER expose this
    private LocalDateTime createdAt;
    @OneToMany(mappedBy = "user", fetch = FetchType.LAZY)
    private List<Order> orders;        // serialising this triggers N+1 queries
}

// Response DTO — record: immutable, concise, zero boilerplate (Java 16+)
public record UserResponse(
    Long id,
    String name,
    String email,
    LocalDateTime createdAt
) {
    // Factory method keeps mapping logic in the DTO, not scattered across controllers
    public static UserResponse from(User user) {
        return new UserResponse(user.getId(), user.getName(), user.getEmail(), user.getCreatedAt());
    }
}

// Separate request DTOs — create and update have different validation rules
public record CreateUserRequest(
    @NotBlank @Size(min = 2, max = 100) String name,
    @NotBlank @Email String email,
    @NotBlank @Size(min = 8, max = 72) String password  // 72 = bcrypt max useful input length
) {}

public record UpdateUserRequest(
    @NotBlank @Size(min = 2, max = 100) String name,
    @NotBlank @Email String email
    // no password — changes go through a dedicated /change-password endpoint
) {}

A Complete REST Controller

@RestController
@RequestMapping("/api/v1/users")
public class UserController {

    private final UserService userService;

    public UserController(UserService userService) { this.userService = userService; }

    // GET /api/v1/users?page=0&size=20&sort=name
    @GetMapping
    public Page<UserResponse> listUsers(
            @RequestParam(defaultValue = "0") int page,
            @RequestParam(defaultValue = "20") @Max(100) int size,
            @RequestParam(defaultValue = "id") String sort) {
        return userService.findAll(PageRequest.of(page, size, Sort.by(sort)));
    }

    // GET /api/v1/users/123
    @GetMapping("/{id}")
    public ResponseEntity<UserResponse> getUser(@PathVariable Long id) {
        return userService.findById(id)
            .map(ResponseEntity::ok)
            .orElseGet(() -> ResponseEntity.notFound().build());
    }

    // POST /api/v1/users  →  201 Created + Location: /api/v1/users/124
    @PostMapping
    public ResponseEntity<UserResponse> createUser(@Valid @RequestBody CreateUserRequest req) {
        UserResponse created = userService.create(req);
        URI location = ServletUriComponentsBuilder.fromCurrentRequest()
            .path("/{id}").buildAndExpand(created.id()).toUri();
        return ResponseEntity.created(location).body(created);
    }

    // PUT /api/v1/users/123  — FULL replace: client MUST send ALL fields
    @PutMapping("/{id}")
    public ResponseEntity<UserResponse> replaceUser(@PathVariable Long id,
                                                @Valid @RequestBody UpdateUserRequest req) {
        return userService.replace(id, req)
            .map(ResponseEntity::ok)
            .orElseGet(() -> ResponseEntity.notFound().build());
    }

    // PATCH /api/v1/users/123  — partial update: only provided fields change
    @PatchMapping("/{id}")
    public ResponseEntity<UserResponse> patchUser(@PathVariable Long id,
                                              @RequestBody Map<String, Object> updates) {
        return userService.patch(id, updates)
            .map(ResponseEntity::ok)
            .orElseGet(() -> ResponseEntity.notFound().build());
    }

    // DELETE /api/v1/users/123  →  204 No Content (idempotent: 204 even if already gone)
    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
        userService.delete(id);
        return ResponseEntity.noContent().build();
    }
}

Validation

// Constraint annotations compose directly on record components
public record CreateUserRequest(
    @NotBlank @Size(min = 2, max = 100) String name,
    @NotBlank @Email String email,
    @NotNull @Min(18) @Max(120) Integer age,
    @NotBlank @Size(min = 8, max = 72) String password,
    @Valid @NotNull AddressRequest address  // @Valid cascades into the nested record
) {}

public record AddressRequest(
    @NotBlank String street,
    @NotBlank @Pattern(regexp = "\\d{5}", message = "Must be a 5-digit postal code") String postalCode
) {}

Error Responses with ProblemDetail (RFC 9457)

Before Spring Framework 6, every team invented its own ErrorResponse class. Spring 6 / Boot 3 ships ProblemDetail — a standardised JSON error shape that clients can parse once and understand across any conforming API.

@RestControllerAdvice
public class GlobalExceptionHandler {

    // Validation failure on @RequestBody — thrown automatically when @Valid fails
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ProblemDetail handleValidation(MethodArgumentNotValidException ex) {
        ProblemDetail p = ProblemDetail.forStatusAndDetail(HttpStatus.BAD_REQUEST, "Validation failed");
        p.setTitle("Validation Error");
        p.setProperty("errors", ex.getBindingResult().getFieldErrors().stream()
            .map(e -> Map.of(
                "field", e.getField(),
                "message", e.getDefaultMessage(),
                "rejected", String.valueOf(e.getRejectedValue())))
            .toList());
        return p;
    }

    // Resource not found
    @ExceptionHandler(ResourceNotFoundException.class)
    public ProblemDetail handleNotFound(ResourceNotFoundException ex) {
        return ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
    }

    // Conflict — duplicate email, optimistic locking failure, etc.
    @ExceptionHandler(DuplicateResourceException.class)
    public ProblemDetail handleConflict(DuplicateResourceException ex) {
        ProblemDetail p = ProblemDetail.forStatusAndDetail(HttpStatus.CONFLICT, ex.getMessage());
        p.setProperty("conflictingField", ex.getField());
        return p;
    }

    // Catch-all — log internally, never leak stack traces to callers
    @ExceptionHandler(Exception.class)
    public ProblemDetail handleUnexpected(Exception ex) {
        log.error("Unexpected error", ex);
        return ProblemDetail.forStatusAndDetail(HttpStatus.INTERNAL_SERVER_ERROR,
            "An unexpected error occurred");
    }
}

// RFC 9457 response shape — consistent across every endpoint:
// {
//   "type":   "about:blank",
//   "title":  "Validation Error",
//   "status": 400,
//   "detail": "Validation failed",
//   "errors": [{ "field": "email", "message": "must be a well-formed email address" }]
// }

# application.properties — also enables ProblemDetail for Spring's own built-in exceptions
spring.mvc.problemdetails.enabled=true

API Versioning

// URI versioning
@RestController @RequestMapping("/api/v1/users")
public class UserControllerV1 { ... }

@RestController @RequestMapping("/api/v2/users")
public class UserControllerV2 { ... }

// Header versioning
@GetMapping(value = "/api/users/{id}", headers = "X-API-Version=2")
public UserResponseV2 getUserV2(@PathVariable Long id) { ... }

// Content negotiation
@GetMapping(value = "/api/users/{id}", produces = "application/vnd.company.user.v2+json")
public UserResponseV2 getUserV2(@PathVariable Long id) { ... }

Pagination

@GetMapping
public Page<UserResponse> listUsers(
        @RequestParam(defaultValue = "0") int page,
        @RequestParam(defaultValue = "20") @Max(100) int size,   // @Max protects the DB
        @RequestParam(defaultValue = "id") String sort) {
    return userService.findAll(PageRequest.of(page, size, Sort.by(sort)))
        .map(UserResponse::from);
}

// Page<T> serialises to:
// { "content":[...], "totalElements":150, "totalPages":8,
//   "number":0, "size":20, "first":true, "last":false }

The Page vs Slice trade-off (whether to pay the extra COUNT(*) cost) is in Spring Data JPA — Pagination. The REST-layer concern here is the @Max(100) guard — without it, ?size=1000000 loads your entire table in a single request.

Calling Other APIs with RestClient

@Service
public class ExternalApiService {

    private final RestClient restClient;

    // RestClient.Builder is auto-configured by Boot — inject and customise, don't new it
    public ExternalApiService(RestClient.Builder builder) {
        this.restClient = builder
            .baseUrl("https://api.example.com")
            .defaultHeader("Accept", "application/json")
            .requestInterceptor((req, body, execution) -> {
                req.getHeaders().setBearerAuth(tokenProvider.getToken());
                return execution.execute(req, body);
            })
            .build();
    }

    // GET — deserialise body directly
    public UserResponse getUser(Long id) {
        return restClient.get()
            .uri("/users/{id}", id)
            .retrieve()
            .onStatus(HttpStatusCode::is4xxClientError, (req, res) -> {
                throw new ResourceNotFoundException("User not found: " + id);
            })
            .body(UserResponse.class);
    }

    // GET list — ParameterizedTypeReference for generic types
    public List<UserResponse> getAllUsers() {
        return restClient.get()
            .uri("/users")
            .retrieve()
            .body(new ParameterizedTypeReference<List<UserResponse>>() {});
    }

    // POST with request body
    public UserResponse createUser(CreateUserRequest request) {
        return restClient.post()
            .uri("/users")
            .contentType(MediaType.APPLICATION_JSON)
            .body(request)
            .retrieve()
            .body(UserResponse.class);
    }
}

Testing REST Endpoints with MockMvc

@WebMvcTest(UserController.class)  // loads ONLY the web layer — no DB, no full context
class UserControllerTest {

    @Autowired private MockMvc mockMvc;
    @Autowired private ObjectMapper objectMapper;
    @MockitoBean private UserService userService;  // @MockBean before Boot 3.4

    @Test
    void getUser_whenExists_returns200() throws Exception {
        var user = new UserResponse(1L, "Ana", "ana@example.com", LocalDateTime.now());
        when(userService.findById(1L)).thenReturn(Optional.of(user));

        mockMvc.perform(get("/api/v1/users/1").accept(MediaType.APPLICATION_JSON))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.id").value(1))
            .andExpect(jsonPath("$.name").value("Ana"))
            .andExpect(jsonPath("$.passwordHash").doesNotExist());  // assert no data leaks
    }

    @Test
    void getUser_whenNotFound_returns404() throws Exception {
        when(userService.findById(99L)).thenReturn(Optional.empty());
        mockMvc.perform(get("/api/v1/users/99"))
            .andExpect(status().isNotFound());
    }

    @Test
    void createUser_whenValid_returns201WithLocation() throws Exception {
        var req = new CreateUserRequest("Ana", "ana@example.com", "securepass", null);
        var res = new UserResponse(1L, "Ana", "ana@example.com", LocalDateTime.now());
        when(userService.create(any())).thenReturn(res);

        mockMvc.perform(post("/api/v1/users")
                .contentType(MediaType.APPLICATION_JSON)
                .content(objectMapper.writeValueAsString(req)).with(csrf()))
            .andExpect(status().isCreated())
            .andExpect(header().exists("Location"))
            .andExpect(jsonPath("$.id").value(1));
    }

    @Test
    void createUser_whenInvalidEmail_returns400() throws Exception {
        var req = new CreateUserRequest("Ana", "not-an-email", "securepass", null);

        mockMvc.perform(post("/api/v1/users")
                .contentType(MediaType.APPLICATION_JSON)
                .content(objectMapper.writeValueAsString(req)).with(csrf()))
            .andExpect(status().isBadRequest())
            .andExpect(jsonPath("$.title").value("Validation Error"))
            .andExpect(jsonPath("$.errors[0].field").value("email"));
    }
}

Interview Questions