RESTful API Principles

What is REST — and What Problem Does It Actually Solve?

REST (Representational State Transfer) is an architectural style for distributed hypermedia systems, defined by Roy Fielding in his 2000 dissertation. It is not a protocol, a standard, or a library. It is a set of six constraints that, when all applied together, produce systems with specific properties: scalability, independent evolution of client and server, and uniform discoverability of behavior.

The practical problem REST solved was the state of web services circa 2000: SOAP APIs required bespoke XML schemas, WSDL files, specialized client tooling, and encoded every operation as a POST body — the HTTP method, status code, and URL were all ignored as semantics. REST said: HTTP already has verbs, status codes, caching, and redirection — use them instead of reinventing them inside the payload.

/*
 * BEFORE REST — SOAP-style: everything is a POST, HTTP is just a transport pipe.
 * The actual operation lives inside the XML envelope.
 */
POST /OrderService HTTP/1.1
Content-Type: text/xml

<soap:Envelope>
  <soap:Body>
    <GetOrderRequest>
      <orderId>9001</orderId>
    </GetOrderRequest>
  </soap:Body>
</soap:Envelope>
// Status code is always 200 — even errors return 200 with a fault envelope.
// Caching is impossible: every call is a POST.
// Any client needs the WSDL to understand what to send.

/*
 * AFTER REST — HTTP semantics do the work; the payload carries only data.
 */
GET /api/v1/orders/9001 HTTP/1.1
Accept: application/json

HTTP/1.1 200 OK
Cache-Control: max-age=60
Content-Type: application/json

{"id": 9001, "status": "SHIPPED", "total": 129.90}
// Any HTTP client understands GET is safe to cache and retry.
// 200 means success. 404 means not found. No schema needed.

The Six REST Constraints

An API is RESTful when it satisfies all six constraints. "REST-like" or "REST-ish" means some are missing — usually statelessness or uniform interface. That's not necessarily wrong, but it means you can't claim the architectural properties REST provides.

1. Client-Server Separation

Client and server are independent: the server doesn't know or care how the client renders data; the client doesn't know or care how the server stores it. They communicate only through the agreed interface. This is why your Spring Boot API can serve a browser SPA, an iOS app, and a CLI tool simultaneously without changing a line of server code.

2. Statelessness

Every request must contain all information needed to process it. The server holds no per-client session state between requests.

// WRONG — server remembers which page the client is on
@GetMapping("/api/orders/next")
public List<OrderResponse> getNextPage(HttpSession session) {
    int page = (int) session.getAttribute("currentPage");  // server state
    return orderService.findPage(page + 1);
    // Any server instance that doesn't have this session will fail.
    // Horizontal scaling requires sticky sessions or session replication.
}

// CORRECT — client sends everything needed
@GetMapping("/api/orders")
public Page<OrderResponse> getOrders(
        @RequestParam(defaultValue = "0") int page,
        @RequestParam(defaultValue = "20") int size,
        @RequestHeader("Authorization") String bearer) {
    // All context in the request: identity (token), page, size.
    // Any instance can handle this.
    return orderService.findPage(page, size);
}

3. Cacheability

Responses must declare themselves as cacheable or not, so clients and intermediaries (CDNs, proxies) can serve repeat requests without touching the origin server. GET responses to read-only data are the most obvious candidates.

@GetMapping("/api/products/{id}")
public ResponseEntity<ProductResponse> getProduct(@PathVariable Long id) {
    ProductResponse product = productService.findById(id);
    return ResponseEntity.ok()
        .cacheControl(CacheControl.maxAge(1, TimeUnit.HOURS))
        .eTag(String.valueOf(product.version()))   // client sends If-None-Match next time → 304 if unchanged
        .body(product);
}

@GetMapping("/api/stock/{productId}")
public ResponseEntity<StockResponse> getStock(@PathVariable Long productId) {
    return ResponseEntity.ok()
        .cacheControl(CacheControl.noCache())   // stock changes too fast to cache
        .body(stockService.findByProduct(productId));
}

4. Uniform Interface

The most distinctive REST constraint. Four sub-constraints: resource identification via URIs; manipulation through representations; self-descriptive messages (the request contains everything needed to process it); and HATEOAS (responses contain links to related state transitions). In practice, most APIs implement the first three and skip HATEOAS — making them REST-like but not strictly RESTful per Fielding. Whether you need full HATEOAS is covered in Section 5 below.

5. Layered System

The client can't tell whether it's talking directly to the origin server or through a CDN, an API gateway, or a load balancer. This is what makes it safe for a CDN to cache GET /api/products/123 without the server needing to know or agree with it explicitly — the caching contract is in the HTTP headers, not in a bilateral agreement.

6. Code on Demand (Optional)

The only optional constraint. The server can extend the client by sending executable code — think JavaScript served with HTML pages. In pure REST APIs this is rarely relevant and almost never used, due to the security implications of executing code from an arbitrary server.

URL Design: Resources, Nouns, and the Decisions That Actually Matter

The Basic Rule: URIs Identify Resources, Methods Are the Verbs

// Good: nouns, plural, lowercase, hyphens for readability
GET    /api/v1/orders              // collection
GET    /api/v1/orders/9001         // single resource
GET    /api/v1/orders/9001/items   // sub-resource
POST   /api/v1/orders              // create
PUT    /api/v1/orders/9001         // full replace
PATCH  /api/v1/orders/9001         // partial update
DELETE /api/v1/orders/9001         // delete

// Bad: verbs in URLs — the HTTP method is already the verb
GET  /api/getOrders           // ✗
POST /api/createOrder         // ✗
GET  /api/deleteOrder/9001    // ✗ using GET to delete is catastrophic (prefetching, bots)

// Action sub-resources: modeling state transitions as resource creation
POST /api/v1/orders/9001/cancellation     // cancel order
POST /api/v1/orders/9001/confirmation     // confirm order
POST /api/v1/payments/555/refunds         // issue refund
POST /api/v1/users/42/password-resets     // trigger password reset

// All are POST (creating a new event/state); all have meaningful nouns in the URL

Filtering, Sorting, and Pagination

// Query params for filtering and sorting — keep them consistent across resources
GET /api/v1/orders?status=PENDING&customerId=42&sort=createdAt,desc&page=0&size=20

@GetMapping
public Page<OrderResponse> getOrders(
        @RequestParam(required = false) OrderStatus status,
        @RequestParam(required = false) Long customerId,
        @RequestParam(defaultValue = "createdAt,desc") String sort,
        @RequestParam(defaultValue = "0") int page,
        @RequestParam(defaultValue = "20") int size) {

    Pageable pageable = PageRequest.of(page, size, Sort.by(parseSortParam(sort)));
    return orderService.findAll(status, customerId, pageable);
}

A Production-Grade REST Controller

The controller below follows all conventions introduced so far: record DTOs, constructor injection, ProblemDetail errors (from HTTP Protocol), proper status codes including 201 + Location, and @Valid on incoming payloads. It deliberately does not return JPA entities.

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

    private final OrderService orderService;

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

    @GetMapping
    public Page<OrderSummary> listOrders(
            @RequestParam(required = false) OrderStatus status,
            @RequestParam(defaultValue = "0") int page,
            @RequestParam(defaultValue = "20") int size) {
        return orderService.findAll(status, PageRequest.of(page, size));
    }

    @GetMapping("/{id}")
    public OrderDetail getOrder(@PathVariable Long id) {
        return orderService.findById(id)
            .orElseThrow(() -> new OrderNotFoundException(id));
    }

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public ResponseEntity<OrderDetail> createOrder(@Valid @RequestBody CreateOrderRequest request) {
        OrderDetail created = orderService.create(request);
        URI location = URI.create("/api/v1/orders/" + created.id());
        return ResponseEntity.created(location).body(created);
    }

    @PatchMapping("/{id}")
    public OrderDetail updateOrder(@PathVariable Long id, @Valid @RequestBody UpdateOrderRequest request) {
        return orderService.update(id, request);
    }

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

    @PostMapping("/{id}/cancellation")
    public OrderDetail cancelOrder(@PathVariable Long id,
                                      @Valid @RequestBody CancellationRequest request) {
        return orderService.cancel(id, request.reason());
    }

    @GetMapping("/{id}/items")
    public List<OrderItem> getItems(@PathVariable Long id) {
        return orderService.findItems(id);
    }
}

// Record DTOs — immutable, compact, no serialization surprises
public record CreateOrderRequest(@NotNull Long productId, @Positive int quantity) {}
public record CancellationRequest(@NotBlank String reason) {}
public record OrderDetail(Long id, OrderStatus status, BigDecimal total, Instant createdAt) {}

Error Responses: Stop Inventing Custom Formats

RFC 9457 (Problem Details) is built into Spring Boot 3.x. It provides a machine-parseable error format with a defined schema so any generic HTTP client can understand your errors. There is no good reason to invent a custom ApiError class in 2026 — you're adding code and inconsistency for no gain.

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(OrderNotFoundException.class)
    public ProblemDetail handleNotFound(OrderNotFoundException ex) {
        ProblemDetail pd = ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
        pd.setTitle("Order not found");
        pd.setProperty("orderId", ex.getOrderId());
        return pd;
    }

    @ExceptionHandler(OrderAlreadyCancelledException.class)
    public ProblemDetail handleConflict(OrderAlreadyCancelledException ex) {
        ProblemDetail pd = ProblemDetail.forStatusAndDetail(HttpStatus.CONFLICT, ex.getMessage());
        pd.setTitle("Order already cancelled");
        return pd;
    }

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ProblemDetail handleValidation(MethodArgumentNotValidException ex) {
        List<String> errors = ex.getBindingResult().getFieldErrors().stream()
            .map(e -> e.getField() + ": " + e.getDefaultMessage())
            .toList();
        ProblemDetail pd = ProblemDetail.forStatusAndDetail(HttpStatus.BAD_REQUEST, "Validation failed");
        pd.setProperty("errors", errors);
        return pd;
    }
}

// Wire format — Content-Type: application/problem+json
// {
//   "type":   "about:blank",
//   "title":  "Order not found",
//   "status": 404,
//   "detail": "No order with id 9001",
//   "orderId": 9001
// }

API Versioning — Four Strategies and When to Use Each

// URL path versioning — separate controller classes, cleanest isolation
@RestController
@RequestMapping("/api/v1/orders")
public class OrderControllerV1 { /* returns OrderV1 response shape */ }

@RestController
@RequestMapping("/api/v2/orders")
public class OrderControllerV2 { /* returns OrderV2 response shape — new fields, different structure */ }

// Accept header versioning — one controller, multiple produces values
@GetMapping(value = "/{id}", produces = "application/vnd.shop.v1+json")
public OrderV1 getOrderV1(@PathVariable Long id) { return orderService.findV1(id); }

@GetMapping(value = "/{id}", produces = "application/vnd.shop.v2+json")
public OrderV2 getOrderV2(@PathVariable Long id) { return orderService.findV2(id); }

HATEOAS — What It Is and When You Actually Need It

HATEOAS (Hypermedia As The Engine Of Application State) is the fourth sub-constraint of Uniform Interface. Responses include hypermedia links that describe available state transitions — the client discovers what it can do next from the response, rather than hard-coding URLs.

// Without HATEOAS — client hard-codes "/api/v1/orders/{id}/cancellation"
{
    "id": 9001,
    "status": "PENDING",
    "total": 129.90
}

// With HATEOAS — client discovers the next available actions from the response itself
{
    "id": 9001,
    "status": "PENDING",
    "total": 129.90,
    "_links": {
        "self":         { "href": "/api/v1/orders/9001" },
        "items":        { "href": "/api/v1/orders/9001/items" },
        "cancellation": { "href": "/api/v1/orders/9001/cancellation", "method": "POST" }
    }
}

// Spring HATEOAS — add the starter: spring-boot-starter-hateoas
@GetMapping("/{id}")
public EntityModel<OrderDetail> getOrder(@PathVariable Long id) {
    OrderDetail order = orderService.findById(id)
        .orElseThrow(() -> new OrderNotFoundException(id));

    return EntityModel.of(order,
        linkTo(methodOn(OrderController.class).getOrder(id)).withSelfRel(),
        linkTo(methodOn(OrderController.class).getItems(id)).withRel("items"),
        linkTo(methodOn(OrderController.class).cancelOrder(id, null)).withRel("cancellation")
    );
}

REST vs GraphQL vs gRPC

REST is the default, but it's not always the right tool. The choice has real production consequences.

Best Practices and Common Pitfalls

Interview Questions