How do you build a REST API with Spring?

@RestController combines @Controller and @ResponseBody, so return values are serialized, usually to JSON. @RequestMapping sets the base path, and method-level annotations map HTTP verbs and path variables.

@RestController
@RequestMapping("/api/orders")
public class OrderController {
    private final OrderService service;

    public OrderController(OrderService service) {
        this.service = service;
    }

    @GetMapping("/{id}")
    public ResponseEntity<OrderResponse> get(@PathVariable long id) {
        return service.find(id)
            .map(ResponseEntity::ok)
            .orElseGet(() -> ResponseEntity.notFound().build());
    }
}

What separates a good API

• Use nouns for resources and HTTP verbs for actions
• Return 201 with a Location header when creating a resource
• Use 400 for validation errors, 404 for missing resources and 409 for conflicts
• Validate request bodies with @Valid and bean validation annotations
• Centralize error mapping with @ControllerAdvice and a consistent error shape
• Do not expose JPA entities directly; use request and response DTOs

Make writes idempotent where possible, especially for retries and message delivery. For large collections, paginate and document the contract. Version or evolve APIs deliberately rather than changing response fields in place.