REST API Design: Principles, Patterns and Real-World Best Practices

package io.thecodeforge.api.v1;

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.servlet.support.ServletUriComponentsBuilder;
import jakarta.validation.Valid;
import java.net.URI;
import java.util.List;

/**
 * TheCodeForge - REST Resource Controller
 * Resources are plural nouns: /products
 * Actions are HTTP Methods: GET, POST, PUT, DELETE
 * Versioning is in the path: /api/v1/
 */
@RestController
@RequestMapping("/api/v1/products")
public class ProductController {

    private final ProductService productService;

    public ProductController(ProductService productService) {
        this.productService = productService;
    }

    @GetMapping
    public ResponseEntity<Page<ProductResponse>> getAllProducts(
            @RequestParam(defaultValue = "0") int page,
            @RequestParam(defaultValue = "20") int size,
            @RequestParam(required = false) String category,
            @RequestParam(defaultValue = "createdAt") String sortBy,
            @RequestParam(defaultValue = "desc") String order) {
        Page<ProductResponse> products = productService.findAll(page, size, category, sortBy, order);
        return ResponseEntity.ok(products);
    }

    @PostMapping
    public ResponseEntity<ProductResponse> createProduct(@Valid @RequestBody CreateProductRequest request) {
        ProductResponse created = productService.create(request);
        URI location = ServletUriComponentsBuilder
                .fromCurrentRequest()
                .path("/{id}")
                .buildAndExpand(created.getId())
                .toUri();
        // 201 Created with Location header pointing to new resource
        return ResponseEntity.created(location).body(created);
    }

    @GetMapping("/{id}")
    public ResponseEntity<ProductResponse> getProductById(@PathVariable String id) {
        return productService.findById(id)
                .map(ResponseEntity::ok)
                .orElse(ResponseEntity.notFound().build()); // 404 if not found
    }

    @PutMapping("/{id}")
    public ResponseEntity<ProductResponse> updateProduct(
            @PathVariable String id,
            @Valid @RequestBody UpdateProductRequest request) {
        return productService.update(id, request)
                .map(ResponseEntity::ok)
                .orElse(ResponseEntity.notFound().build());
    }

    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteProduct(@PathVariable String id) {
        boolean deleted = productService.delete(id);
        return deleted ? ResponseEntity.noContent().build() : ResponseEntity.notFound().build();
    }
}

package io.thecodeforge.api.exception;

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import jakarta.servlet.http.HttpServletRequest;
import java.time.Instant;
import java.util.List;
import java.util.stream.Collectors;

/**
 * TheCodeForge - Global Exception Handler
 * Maps exceptions to proper HTTP status codes and consistent error envelopes.
 * Never return 200 for errors. Never expose stack traces.
 */
@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<ErrorResponse> handleNotFound(ResourceNotFoundException ex, HttpServletRequest request) {
        ErrorResponse error = ErrorResponse.builder()
                .status(404)
                .code("RESOURCE_NOT_FOUND")
                .message(ex.getMessage())
                .path(request.getRequestURI())
                .timestamp(Instant.now())
                .build();
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(error);
    }

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ErrorResponse> handleValidation(MethodArgumentNotValidException ex, HttpServletRequest request) {
        List<FieldError> fieldErrors = ex.getBindingResult().getFieldErrors().stream()
                .map(fe -> new FieldError(fe.getField(), fe.getDefaultMessage()))
                .collect(Collectors.toList());
        ErrorResponse error = ErrorResponse.builder()
                .status(400)
                .code("VALIDATION_FAILED")
                .message("Request validation failed")
                .path(request.getRequestURI())
                .timestamp(Instant.now())
                .errors(fieldErrors)
                .build();
        return ResponseEntity.badRequest().body(error);
    }

    @ExceptionHandler(DuplicateResourceException.class)
    public ResponseEntity<ErrorResponse> handleConflict(DuplicateResourceException ex, HttpServletRequest request) {
        ErrorResponse error = ErrorResponse.builder()
                .status(409)
                .code("DUPLICATE_RESOURCE")
                .message(ex.getMessage())
                .path(request.getRequestURI())
                .timestamp(Instant.now())
                .build();
        return ResponseEntity.status(HttpStatus.CONFLICT).body(error);
    }

    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleUnexpected(Exception ex, HttpServletRequest request) {
        // Log the full stack trace server-side, never expose to clients
        log.error("Unhandled exception at {}: {}", request.getRequestURI(), ex.getMessage(), ex);
        ErrorResponse error = ErrorResponse.builder()
                .status(500)
                .code("INTERNAL_ERROR")
                .message("An unexpected error occurred. Please try again later.")
                .path(request.getRequestURI())
                .timestamp(Instant.now())
                .build();
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(error);
    }
}

package io.thecodeforge.api.security;

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.security.core.authority.SimpleGrantedAuthority;
import org.springframework.web.filter.OncePerRequestFilter;
import java.io.IOException;
import java.util.List;
import java.util.stream.Collectors;

/**
 * TheCodeForge - Stateless JWT Authentication Filter
 * Every request carries its own auth — no server-side sessions.
 * This is what enables horizontal scaling without sticky sessions.
 */
public class JwtAuthenticationFilter extends OncePerRequestFilter {

    private final JwtTokenProvider tokenProvider;

    public JwtAuthenticationFilter(JwtTokenProvider tokenProvider) {
        this.tokenProvider = tokenProvider;
    }

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                    HttpServletResponse response,
                                    FilterChain filterChain) throws ServletException, IOException {
        String authHeader = request.getHeader("Authorization");

        if (authHeader != null && authHeader.startsWith("Bearer ")) {
            String token = authHeader.substring(7);
            try {
                if (tokenProvider.validateToken(token)) {
                    String userId = tokenProvider.getUserId(token);
                    List<String> roles = tokenProvider.getRoles(token);
                    List<SimpleGrantedAuthority> authorities = roles.stream()
                            .map(SimpleGrantedAuthority::new)
                            .collect(Collectors.toList());

                    UsernamePasswordAuthenticationToken auth =
                            new UsernamePasswordAuthenticationToken(userId, null, authorities);
                    SecurityContextHolder.getContext().setAuthentication(auth);
                }
            } catch (JwtException e) {
                // Invalid token — clear context and let the request proceed unauthenticated
                // The endpoint's @PreAuthorize will reject if auth is required
                SecurityContextHolder.clearContext();
            }
        }

        filterChain.doFilter(request, response);
    }
}

package io.thecodeforge.api;

/**
 * TheCodeForge - API Versioning with URL Path Strategy
 * v1 returns the original shape. v2 returns the evolved shape.
 * Both exist simultaneously until v1 is deprecated and sunset.
 */

// V1 Controller - Original response shape
@RestController
@RequestMapping("/api/v1/products")
public class ProductControllerV1 {

    @GetMapping("/{id}")
    public ResponseEntity<ProductV1Response> getProduct(@PathVariable String id) {
        Product product = productService.findById(id);
        // V1 response: flat structure, price as double
        return ResponseEntity.ok(new ProductV1Response(
                product.getId(),
                product.getName(),
                product.getPrice()  // double
        ));
    }
}

// V2 Controller - Evolved response shape
@RestController
@RequestMapping("/api/v2/products")
public class ProductControllerV2 {

    @GetMapping("/{id}")
    public ResponseEntity<ProductV2Response> getProduct(@PathVariable String id) {
        Product product = productService.findById(id);
        // V2 response: nested structure, price as Money object
        return ResponseEntity.ok(new ProductV2Response(
                product.getId(),
                product.getName(),
                new Money(product.getPrice(), product.getCurrency()),  // structured
                product.getInventory()  // new field in v2
        ));
    }
}

// DTOs
record ProductV1Response(String id, String name, double price) {}

record ProductV2Response(String id, String name, Money price, InventoryStatus inventory) {}

record Money(BigDecimal amount, String currency) {}

record InventoryStatus(int available, int reserved) {}

package io.thecodeforge.api.pagination;

import java.util.List;

/**
 * TheCodeForge - Cursor-Based Pagination Response
 * Cursor encodes last-seen position in sort order.
 * More stable than offset for high-velocity tables.
 */
public record PaginatedResponse<T>(
        List<T> data,
        Pagination pagination
) {
    public record Pagination(
            int size,
            String nextCursor,  // null if no more pages
            String prevCursor,  // null if first page
            boolean hasMore
    ) {}
}

// Repository implementation
@Repository
public class ProductRepository {

    public PaginatedResponse<Product> findWithCursor(String cursor, int limit) {
        CursorData cursorData = cursor != null ? decodeCursor(cursor) : null;

        // Query: fetch limit+1 to check if there are more
        List<Product> products;
        if (cursorData == null) {
            products = jdbcTemplate.query(
                    "SELECT * FROM products ORDER BY created_at DESC, id DESC LIMIT ?",
                    productRowMapper, limit + 1
            );
        } else {
            products = jdbcTemplate.query(
                    "SELECT * FROM products " +
                    "WHERE (created_at, id) < (?, ?) " +
                    "ORDER BY created_at DESC, id DESC LIMIT ?",
                    productRowMapper, cursorData.createdAt(), cursorData.id(), limit + 1
            );
        }

        boolean hasMore = products.size() > limit;
        if (hasMore) {
            products = products.subList(0, limit);  // Remove the extra row
        }

        String nextCursor = hasMore ? encodeCursor(products.get(products.size() - 1)) : null;

        return new PaginatedResponse<>(products, new Pagination(limit, nextCursor, cursor, hasMore));
    }

    private String encodeCursor(Product p) {
        return Base64.getEncoder().encodeToString(
                String.format("{\"created_at\":\"%s\",\"id\":\"%s\"}",
                        p.getCreatedAt().toString(), p.getId()).getBytes());
    }

    private CursorData decodeCursor(String cursor) {
        // Decode and parse — error handling omitted for brevity
        String json = new String(Base64.getDecoder().decode(cursor));
        // Parse JSON to CursorData record
        return parseJson(json);
    }
}

package io.thecodeforge.api.v1;

import org.springframework.hateoas.EntityModel;
import org.springframework.hateoas.CollectionModel;
import org.springframework.hateoas.server.mvc.WebMvcLinkBuilder;
import org.springframework.web.bind.annotation.*;
import java.util.List;
import java.util.stream.Collectors;

import static org.springframework.hateoas.server.mvc.WebMvcLinkBuilder.*;

/**
 * TheCodeForge - HATEOAS Implementation with Spring
 * Responses include navigational links enabling API discoverability.
 * Level 3 Richardson Maturity Model.
 */
@RestController
@RequestMapping("/api/v1/products")
public class HateoasProductController {

    @GetMapping("/{id}")
    public EntityModel<ProductResponse> getProduct(@PathVariable String id) {
        Product product = productService.findById(id);
        ProductResponse response = toResponse(product);

        return EntityModel.of(response,
                linkTo(methodOn(HateoasProductController.class).getProduct(id)).withSelfRel(),
                linkTo(methodOn(ReviewController.class).getReviewsForProduct(id)).withRel("reviews"),
                linkTo(methodOn(CartController.class).addToCart(id, null)).withRel("add-to-cart"),
                linkTo(methodOn(HateoasProductController.class).getAllProducts(0, 20)).withRel("collection")
        );
    }

    @GetMapping
    public CollectionModel<EntityModel<ProductResponse>> getAllProducts(
            @RequestParam(defaultValue = "0") int page,
            @RequestParam(defaultValue = "20") int size) {
        List<EntityModel<ProductResponse>> products = productService.findAll(page, size).stream()
                .map(p -> EntityModel.of(toResponse(p),
                        linkTo(methodOn(HateoasProductController.class).getProduct(p.getId())).withSelfRel()))
                .collect(Collectors.toList());

        return CollectionModel.of(products,
                linkTo(methodOn(HateoasProductController.class).getAllProducts(page, size)).withSelfRel(),
                linkTo(methodOn(HateoasProductController.class).getAllProducts(page + 1, size)).withRel("next")
        );
    }
}