REST Architectural Constraints — What Makes an API Truly RESTful

@RestController
@RequestMapping(value = "/orders", produces = MediaType.APPLICATION_JSON_VALUE)
public class OrderController {

    private final OrderService service;
    private final OrderMapper mapper;

    // ---- Uniform interface: resource URL + standard HTTP verbs + HATEOAS links ----
    @GetMapping("/{id}")
    public ResponseEntity<EntityModel<OrderDto>> get(@PathVariable Long id,
                                                      WebRequest request) {
        Order order = service.find(id);

        // ---- Cacheable: ETag + conditional GET ----
        String etag = """ + order.getVersion() + """;
        if (request.checkNotModified(etag)) {
            return ResponseEntity.status(HttpStatus.NOT_MODIFIED).eTag(etag).build();
        }

        EntityModel<OrderDto> model = EntityModel.of(mapper.toDto(order),
            linkTo(methodOn(OrderController.class).get(id, null)).withSelfRel(),
            linkTo(methodOn(OrderController.class).cancel(id)).withRel("cancel"));

        return ResponseEntity.ok()
            .eTag(etag)
            .cacheControl(CacheControl.maxAge(30, TimeUnit.SECONDS).cachePublic())
            .body(model);
    }

    // ---- Stateless: every request carries its own auth; no session ----
    @PostMapping
    public ResponseEntity<OrderDto> create(@Valid @RequestBody OrderRequest req,
                                           @RequestHeader("Idempotency-Key") String key,
                                           @AuthenticationPrincipal Jwt jwt) {
        Order order = service.createIdempotent(req, key, jwt.getSubject());
        URI location = linkTo(methodOn(OrderController.class).get(order.getId(), null)).toUri();
        return ResponseEntity.created(location).body(mapper.toDto(order));
    }

    @DeleteMapping("/{id}")
    public ResponseEntity<Void> cancel(@PathVariable Long id) {
        service.cancel(id);
        return ResponseEntity.noContent().build();
    }
}