Safe HTTP Methods

Direct Answer

Safe HTTP methods are methods whose defined request semantics are essentially read-only: GET, HEAD, OPTIONS, and TRACE. They may still cause incidental work such as access logging; safety means the client did not ask for an application-state change.

Deep Dive & Architecture

Safety is judged by the effect the client requests, not by the annotation or function name. A @GetMapping handler that calls cancellation logic is still an unsafe operation wearing a GET label. Logging the read is different because the client did not ask for the log entry as the result of the request.

At the HTTP boundary, keep reads and commands separate. A link or automated reader can retrieve an order with GET without changing it. Cancellation gets its own unsafe endpoint, where the API can apply authorization, validation, and any retry rule required by that command.

A useful test records the order state, calls the GET endpoint, and proves the state did not change. A separate test calls the cancellation endpoint and checks the intended transition. This tests the behavioral promise instead of trusting the annotation alone.

Code Example

@GetMapping("/orders/{id}")
OrderResponse find(@PathVariable("id") long id) {
    return orders.find(id);
}

@PostMapping("/orders/{id}/cancellation")
ResponseEntity<Void> cancel(
        @PathVariable("id") long id,
        @Valid @RequestBody CancelOrderRequest request) {
    orders.cancel(id, request.reason());
    return ResponseEntity.noContent().build();
}

CancelOrderRequest is the validated request DTO that carries the cancellation reason. The GET handler only retrieves the order, while the separate POST makes the requested state change visible in the HTTP contract. The exact cancellation design can also use a documented state update; the important rule is that cancellation must not pretend to be a safe retrieval.