Response handling — ResponseEntity, status code, header, content negotiation

// Cach 1: return DTO truc tiep (default 200 OK)
@GetMapping("/orders/{id}")
public OrderDto get(@PathVariable Long id) {
    return orderService.findById(id);
}

// Cach 2: ResponseEntity (full control)
@GetMapping("/orders/{id}")
public ResponseEntity<OrderDto> get(@PathVariable Long id) {
    OrderDto order = orderService.findById(id);
    return ResponseEntity.ok()
        .header("X-Cache", "HIT")
        .lastModified(order.updatedAt())
        .body(order);
}

// Cach 3: ResponseEntity.notFound() / ResponseEntity.status(...)
@GetMapping("/orders/{id}")
public ResponseEntity<OrderDto> get(@PathVariable Long id) {
    return orderService.findOptional(id)
        .map(ResponseEntity::ok)
        .orElseGet(() -> ResponseEntity.notFound().build());
}

// 201 Created với Location header
@PostMapping("/orders")
public ResponseEntity<OrderDto> create(@Valid @RequestBody OrderRequest req) {
    OrderDto created = orderService.create(req);
    URI location = ServletUriComponentsBuilder.fromCurrentRequest()
        .path("/{id}").buildAndExpand(created.id()).toUri();
    return ResponseEntity.created(location).body(created);
}

// 204 No Content cho DELETE
@DeleteMapping("/orders/{id}")
@ResponseStatus(HttpStatus.NO_CONTENT)
public void delete(@PathVariable Long id) {
    orderService.delete(id);
}

// 202 Accepted cho async
@PostMapping("/orders/{id}/export")
public ResponseEntity<Void> exportAsync(@PathVariable Long id) {
    String jobId = exportService.startExportJob(id);
    return ResponseEntity.accepted()
        .header("X-Job-Id", jobId)
        .build();
}

@GetMapping("/orders/{id}")
public ResponseEntity<OrderDto> get(
    @PathVariable Long id,
    @RequestHeader(value = "If-Modified-Since", required = false) Long lastFetched
) {
    OrderDto order = orderService.findById(id);
    if (lastFetched != null && order.updatedAt().toEpochMilli() <= lastFetched) {
        return ResponseEntity.status(HttpStatus.NOT_MODIFIED).build();
    }
    return ResponseEntity.ok()
        .lastModified(order.updatedAt())
        .body(order);
}

ResponseEntity.ok(body)                                    // 200 + body
ResponseEntity.ok()                                         // 200 builder, can chain
    .header("X-Custom", "value")
    .contentType(MediaType.APPLICATION_JSON)
    .body(dto)

ResponseEntity.created(uri)                                 // 201 + Location
    .body(dto)

ResponseEntity.accepted()                                   // 202

ResponseEntity.noContent()                                  // 204
    .build()

ResponseEntity.notFound()                                   // 404
    .build()

ResponseEntity.badRequest()                                 // 400
    .body(errorDetails)

ResponseEntity.status(HttpStatus.CONFLICT)                  // any status
    .body(error)

ResponseEntity.unprocessableEntity()                        // 422
    .body(violations)

public ResponseEntity<OrderDto> get() { ... }
public ResponseEntity<List<OrderDto>> list() { ... }
public ResponseEntity<Void> delete() { ... }
public ResponseEntity<?> dynamic() { ... }                  // ? cho any type

return ResponseEntity.ok()
    .header("X-Total-Count", String.valueOf(total))
    .header("X-Page-Number", String.valueOf(page))
    .body(orders);

@GetMapping("/orders/{id}")
public ResponseEntity<OrderDto> get(
    @PathVariable Long id,
    @RequestHeader(value = "If-None-Match", required = false) String ifNoneMatch
) {
    OrderDto order = orderService.findById(id);
    String etag = "\"" + order.version() + "\"";

    if (etag.equals(ifNoneMatch)) {
        return ResponseEntity.status(HttpStatus.NOT_MODIFIED).build();
    }

    return ResponseEntity.ok()
        .eTag(etag)
        .body(order);
}

@Bean
public Filter shallowEtagHeaderFilter() {
    return new ShallowEtagHeaderFilter();
}

spring:
  web:
    resources:
      cache:
        use-last-modified: true

@GetMapping("/orders/{id}/invoice")
public ResponseEntity<Resource> downloadInvoice(@PathVariable Long id) throws IOException {
    Path file = invoiceService.generatePdf(id);
    Resource resource = new FileSystemResource(file);

    return ResponseEntity.ok()
        .contentType(MediaType.APPLICATION_PDF)
        .header(HttpHeaders.CONTENT_DISPOSITION,
            "attachment; filename=\"invoice-" + id + ".pdf\"")
        .body(resource);
}

@GetMapping("/orders/export")
public ResponseEntity<StreamingResponseBody> export() {
    StreamingResponseBody stream = outputStream -> {
        try (OutputStream os = outputStream;
             Stream<Order> orders = orderService.streamAll()) {
            orders.forEach(order -> {
                try {
                    os.write(toCsv(order).getBytes());
                } catch (IOException e) {
                    throw new UncheckedIOException(e);
                }
            });
        }
    };

    return ResponseEntity.ok()
        .contentType(MediaType.parseMediaType("text/csv"))
        .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=\"orders.csv\"")
        .body(stream);
}

@GetMapping(value = "/orders/feed", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public SseEmitter feed() {
    SseEmitter emitter = new SseEmitter(Long.MAX_VALUE);

    eventBus.subscribe(event -> {
        try {
            emitter.send(SseEmitter.event()
                .id(String.valueOf(event.id()))
                .name("order-update")
                .data(event));
        } catch (IOException e) {
            emitter.completeWithError(e);
        }
    });

    return emitter;
}

{
  "success": true,
  "data": { ... },
  "timestamp": "2026-04-15T10:00:00Z",
  "requestId": "abc123"
}

@RestControllerAdvice
public class ApiResponseAdvice implements ResponseBodyAdvice<Object> {

    public boolean supports(MethodParameter returnType,
                             Class<? extends HttpMessageConverter<?>> converterType) {
        // skip if return type is already wrapped
        return !returnType.getParameterType().equals(ApiResponse.class);
    }

    public Object beforeBodyWrite(Object body, MethodParameter returnType,
                                   MediaType contentType, Class<? extends HttpMessageConverter<?>> converterType,
                                   ServerHttpRequest request, ServerHttpResponse response) {
        return ApiResponse.success(body, MDC.get("requestId"));
    }
}

public record ApiResponse<T>(
    boolean success,
    T data,
    Instant timestamp,
    String requestId
) {
    public static <T> ApiResponse<T> success(T data, String requestId) {
        return new ApiResponse<>(true, data, Instant.now(), requestId);
    }
}

{
  "id": 42,
  "customer": "Alice",
  "total": 99.99,
  "_links": {
    "self": {"href": "/api/orders/42"},
    "cancel": {"href": "/api/orders/42/cancel"},
    "items": {"href": "/api/orders/42/items"}
  }
}

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-hateoas</artifactId>
</dependency>

@GetMapping("/orders/{id}")
public EntityModel<OrderDto> get(@PathVariable Long id) {
    OrderDto order = orderService.findById(id);
    return EntityModel.of(order,
        linkTo(methodOn(OrderController.class).get(id)).withSelfRel(),
        linkTo(methodOn(OrderController.class).cancel(id)).withRel("cancel"),
        linkTo(methodOn(OrderController.class).items(id)).withRel("items")
    );
}

@RestController
@RequestMapping("/api/v1/orders")
public class OrderController {

    @GetMapping("/{id}")
    public OrderDto get(@PathVariable Long id) {
        return orderService.findById(id);
        // 200 OK (default), throw 404 if not found
    }

    @GetMapping
    public Page<OrderDto> list(Pageable pageable) {
        return orderService.list(pageable);
        // 200 OK
    }

    @PostMapping
    public ResponseEntity<OrderDto> create(@Valid @RequestBody OrderRequest req) {
        OrderDto created = orderService.create(req);
        URI location = ServletUriComponentsBuilder.fromCurrentRequest()
            .path("/{id}").buildAndExpand(created.id()).toUri();
        return ResponseEntity.created(location).body(created);
        // 201 Created với Location
    }

    @PutMapping("/{id}")
    public OrderDto update(@PathVariable Long id, @Valid @RequestBody OrderRequest req) {
        return orderService.replace(id, req);
        // 200 OK với body update
    }

    @DeleteMapping("/{id}")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void delete(@PathVariable Long id) {
        orderService.delete(id);
        // 204 No Content
    }
}

@GetMapping
public ResponseEntity<List<OrderDto>> list(Pageable pageable) {
    Page<OrderDto> page = orderService.list(pageable);
    return ResponseEntity.ok()
        .header("X-Total-Count", String.valueOf(page.getTotalElements()))
        .header("X-Page-Number", String.valueOf(page.getNumber()))
        .header("X-Page-Size", String.valueOf(page.getSize()))
        .header("X-Total-Pages", String.valueOf(page.getTotalPages()))
        .body(page.getContent());
}

Link: </orders?page=1>; rel="next", </orders?page=10>; rel="last"

{
  "content": [...],
  "pageable": {...},
  "totalElements": 100,
  "totalPages": 5
}

{
  "type": "https://api.olhub.org/errors/validation",
  "title": "Validation failed",
  "status": 400,
  "detail": "Field 'customer' must not be blank",
  "instance": "/api/v1/orders",
  "violations": [
    {"field": "customer", "message": "must not be blank"}
  ]
}

@GetMapping("/orders/{id}")
public ResponseEntity<OrderDto> get(@PathVariable Long id) {
    Order order = service.findById(id);
    String etag = "\"" + order.getVersion() + "\"";

    return ResponseEntity.ok()
        .eTag(etag)
        .cacheControl(CacheControl.maxAge(60, TimeUnit.SECONDS).cachePublic())
        .body(OrderDto.from(order));
}

spring:
  web:
    filter:
      shallow-etag-header:
        enabled: true

server:
  compression:
    enabled: true
    mime-types: application/json,text/html,text/css,application/xml
    min-response-size: 1024              # vuot 1KB compress

@GetMapping("/exports/orders.csv")
public ResponseEntity<StreamingResponseBody> exportCsv() {
    StreamingResponseBody stream = out -> {
        try (PrintWriter w = new PrintWriter(out)) {
            orderService.streamAll().forEach(order -> {
                w.printf("%d,%s,%s%n", order.id(), order.customer(), order.total());
            });
        }
    };

    return ResponseEntity.ok()
        .contentType(MediaType.parseMediaType("text/csv"))
        .header("Content-Disposition", "attachment; filename=\"orders.csv\"")
        .body(stream);
}

@GetMapping(value = "/orders/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public SseEmitter stream() {
    SseEmitter emitter = new SseEmitter(30_000L);    // 30s timeout
    eventBus.subscribe(orderEvent -> {
        try {
            emitter.send(orderEvent);
        } catch (IOException e) {
            emitter.completeWithError(e);
        }
    });
    return emitter;
}

@Configuration
public class SecurityHeadersConfig {

    @Bean
    public FilterRegistrationBean<HeaderFilter> headerFilter() {
        return new FilterRegistrationBean<>(new HeaderFilter() {
            void apply(HttpServletResponse res) {
                res.setHeader("X-Content-Type-Options", "nosniff");
                res.setHeader("X-Frame-Options", "DENY");
                res.setHeader("Strict-Transport-Security", "max-age=31536000; includeSubDomains");
                res.setHeader("Content-Security-Policy", "default-src 'self'");
                res.setHeader("Referrer-Policy", "strict-origin-when-cross-origin");
            }
        });
    }
}

return ResponseEntity.ok(orderDto);    // verbose nếu chỉ default 200

List<Order> all = orderService.findAll();    // 1M record vao memory → OOM
return ResponseEntity.ok(all);

return ResponseEntity.ok().contentType(MediaType.APPLICATION_PDF).body(resource);

@GetMapping("/orders/{id}")
public OrderDto get(@PathVariable Long id) {
    OrderDto order = repo.findById(id);
    if (order == null) throw new RuntimeException("not found");    // 500!
    return order;
}