ResponseEntity and HTTP Status Codes in Spring Boot

//ResponseApp.java
package com.javabrahman.rest.response;

import java.net.URI;
import java.time.Duration;
import java.util.List;
import java.util.Map;
import java.util.Optional;
import java.util.UUID;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.atomic.AtomicLong;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.http.CacheControl;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.context.request.WebRequest;
import org.springframework.web.servlet.support.ServletUriComponentsBuilder;

record Book(Long id, String title, int version) {
}

// What a client sends to create a book: the server chooses the id and the version
record NewBook(String title) {
}

@RestController
@RequestMapping("/api/books")
class BookController {
  private final Map<Long, Book> books = new ConcurrentHashMap<>(Map.of(1L, new Book(1L, "Effective Java", 3)));
  private final AtomicLong nextId = new AtomicLong(1);

  // 200 with a custom header, or the list
  @GetMapping
  ResponseEntity<List<Book>> all() {
    List<Book> list = books.values().stream().toList();
    return ResponseEntity.ok()
        .header("X-Total-Count", String.valueOf(list.size()))
        .body(list);
  }

  // 200 with the book, or 404 when the Optional is empty
  @GetMapping("/{id}")
  ResponseEntity<Book> one(@PathVariable long id) {
    return ResponseEntity.of(Optional.ofNullable(books.get(id)));
  }

  // 201 with a Location header pointing to the new book
  @PostMapping
  ResponseEntity<Book> create(@RequestBody NewBook book) {
    Book saved = new Book(nextId.incrementAndGet(), book.title(), 1);
    books.put(saved.id(), saved);
    URI location = ServletUriComponentsBuilder.fromCurrentRequest()
        .path("/{id}").buildAndExpand(saved.id()).toUri();
    return ResponseEntity.created(location).body(saved);
  }

  // 200 with caching headers, or 304 if the client's copy is current
  @GetMapping("/{id}/cached")
  ResponseEntity<Book> cached(@PathVariable long id, WebRequest request) {
    Book book = books.get(id);
    if (book == null) {
      return ResponseEntity.notFound().build();
    }
    String etag = "\"" + book.id() + "-v" + book.version() + "\"";
    if (request.checkNotModified(etag)) {
      return null;   // Spring has already set status 304 and the ETag header
    }
    return ResponseEntity.ok()
        .eTag(etag)
        .cacheControl(CacheControl.maxAge(Duration.ofMinutes(10)).cachePublic())
        .body(book);
  }
}

record ReportJob(String id, String status) {
}

@RestController
@RequestMapping("/api/reports")
class ReportController {
  private final Map<String, ReportJob> jobs = new ConcurrentHashMap<>();

  // 202: the report is generated in the background; the client polls the Location
  @PostMapping
  ResponseEntity<ReportJob> start() {
    ReportJob job = new ReportJob(UUID.nameUUIDFromBytes("sales-report".getBytes()).toString().substring(0, 8), "QUEUED");
    jobs.put(job.id(), job);
    URI status = ServletUriComponentsBuilder.fromCurrentRequest().path("/{id}").buildAndExpand(job.id()).toUri();
    return ResponseEntity.accepted().location(status).body(job);
  }

  // any status code, here 409 Conflict
  @PostMapping("/{id}/cancel")
  ResponseEntity<String> cancel(@PathVariable String id) {
    return ResponseEntity.status(HttpStatus.CONFLICT).body("Job " + id + " has already started and cannot be cancelled");
  }
}

@SpringBootApplication
public class ResponseApp {
  public static void main(String[] args) {
    SpringApplication.run(ResponseApp.class, args);
  }
}