🔢 API Versioning Strategies

// ===== V1 Controller =====
@RestController
@RequestMapping("/api/v1/orders")
public class OrderControllerV1 {

    private final OrderService orderService;

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

    @GetMapping("/{orderId}")
    public ResponseEntity<OrderResponseV1> getOrder(@PathVariable String orderId) {
        Order order = orderService.findById(orderId);
        return ResponseEntity.ok(OrderResponseV1.from(order));
    }

    @PostMapping
    public ResponseEntity<OrderResponseV1> createOrder(@Valid @RequestBody CreateOrderRequestV1 request) {
        Order order = orderService.create(request.toCommand());
        URI location = URI.create("/api/v1/orders/" + order.getId());
        return ResponseEntity.created(location).body(OrderResponseV1.from(order));
    }
}

// ===== V2 Controller (adds pagination, enriched response) =====
@RestController
@RequestMapping("/api/v2/orders")
public class OrderControllerV2 {

    private final OrderService orderService;
    private final CustomerService customerService;

    public OrderControllerV2(OrderService orderService, CustomerService customerService) {
        this.orderService = orderService;
        this.customerService = customerService;
    }

    @GetMapping("/{orderId}")
    public ResponseEntity<OrderResponseV2> getOrder(@PathVariable String orderId) {
        Order order = orderService.findById(orderId);
        CustomerSummary customer = customerService.getSummary(order.getCustomerId());
        return ResponseEntity.ok(OrderResponseV2.from(order, customer));
    }

    @GetMapping
    public ResponseEntity<PagedResponse<OrderResponseV2>> listOrders(
            @RequestParam(defaultValue = "0") int page,
            @RequestParam(defaultValue = "20") int size,
            @RequestParam(defaultValue = "createdAt,desc") String sort) {

        Page<Order> orders = orderService.findAll(PageRequest.of(page, size, Sort.by(sort)));
        List<OrderResponseV2> items = orders.stream()
                .map(o -> OrderResponseV2.from(o, customerService.getSummary(o.getCustomerId())))
                .toList();

        return ResponseEntity.ok(new PagedResponse<>(items, orders.getTotalElements(), page, size));
    }
}

// ===== V1 Response DTO =====
public record OrderResponseV1(
        String id,
        String customerId,
        BigDecimal totalAmount,
        String status,
        LocalDateTime createdAt
) {
    public static OrderResponseV1 from(Order order) {
        return new OrderResponseV1(
                order.getId(),
                order.getCustomerId(),
                order.getTotalAmount(),
                order.getStatus().name(),
                order.getCreatedAt()
        );
    }
}

// ===== V2 Response DTO (enriched with customer info, structured money) =====
public record OrderResponseV2(
        String id,
        CustomerSummary customer,
        Money totalAmount,
        OrderStatus status,
        List<OrderLineItem> items,
        ShippingInfo shipping,
        LocalDateTime createdAt,
        LocalDateTime updatedAt
) {
    public static OrderResponseV2 from(Order order, CustomerSummary customer) {
        return new OrderResponseV2(
                order.getId(),
                customer,
                new Money(order.getTotalAmount(), order.getCurrency()),
                order.getStatus(),
                order.getItems().stream().map(OrderLineItem::from).toList(),
                ShippingInfo.from(order.getShipping()),
                order.getCreatedAt(),
                order.getUpdatedAt()
        );
    }
}

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

    private final OrderService orderService;
    private final Map<Integer, OrderResponseMapper> versionedMappers;

    public OrderController(OrderService orderService, List<OrderResponseMapper> mappers) {
        this.orderService = orderService;
        this.versionedMappers = mappers.stream()
                .collect(Collectors.toMap(OrderResponseMapper::getVersion, Function.identity()));
    }

    @GetMapping("/{orderId}")
    public ResponseEntity<?> getOrder(
            @PathVariable String orderId,
            @RequestHeader(value = "X-API-Version", defaultValue = "1") int version) {

        Order order = orderService.findById(orderId);
        OrderResponseMapper mapper = versionedMappers.get(version);

        if (mapper == null) {
            throw new UnsupportedApiVersionException(version);
        }

        return ResponseEntity.ok(mapper.map(order));
    }
}

// ===== Version-specific mappers =====
@Component
public class OrderResponseMapperV1 implements OrderResponseMapper {

    @Override
    public int getVersion() { return 1; }

    @Override
    public Object map(Order order) {
        return OrderResponseV1.from(order);
    }
}

@Component
public class OrderResponseMapperV2 implements OrderResponseMapper {

    private final CustomerService customerService;

    public OrderResponseMapperV2(CustomerService customerService) {
        this.customerService = customerService;
    }

    @Override
    public int getVersion() { return 2; }

    @Override
    public Object map(Order order) {
        CustomerSummary customer = customerService.getSummary(order.getCustomerId());
        return OrderResponseV2.from(order, customer);
    }
}

// ===== Custom exception with proper HTTP mapping =====
@ResponseStatus(HttpStatus.BAD_REQUEST)
public class UnsupportedApiVersionException extends RuntimeException {
    public UnsupportedApiVersionException(int version) {
        super("API version " + version + " is not supported. Supported versions: [1, 2]");
    }
}

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

    private final OrderService orderService;
    private final CustomerService customerService;

    // V1 — produces the v1 media type
    @GetMapping(value = "/{orderId}", produces = "application/vnd.company.orders.v1+json")
    public ResponseEntity<OrderResponseV1> getOrderV1(@PathVariable String orderId) {
        Order order = orderService.findById(orderId);
        return ResponseEntity.ok(OrderResponseV1.from(order));
    }

    // V2 — produces the v2 media type
    @GetMapping(value = "/{orderId}", produces = "application/vnd.company.orders.v2+json")
    public ResponseEntity<OrderResponseV2> getOrderV2(@PathVariable String orderId) {
        Order order = orderService.findById(orderId);
        CustomerSummary customer = customerService.getSummary(order.getCustomerId());
        return ResponseEntity.ok(OrderResponseV2.from(order, customer));
    }
}

// ===== Register custom media types in WebMvc configuration =====
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

    @Override
    public void configureContentNegotiation(ContentNegotiationConfigurer configurer) {
        configurer
                .favorParameter(false)
                .ignoreAcceptHeader(false)
                .defaultContentType(MediaType.APPLICATION_JSON)
                .mediaType("v1", MediaType.valueOf("application/vnd.company.orders.v1+json"))
                .mediaType("v2", MediaType.valueOf("application/vnd.company.orders.v2+json"));
    }
}

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

    private final OrderService orderService;
    private final CustomerService customerService;

    @GetMapping("/{orderId}")
    public ResponseEntity<?> getOrder(
            @PathVariable String orderId,
            @RequestParam(value = "version", defaultValue = "1") int version) {

        Order order = orderService.findById(orderId);

        return switch (version) {
            case 1 -> ResponseEntity.ok(OrderResponseV1.from(order));
            case 2 -> {
                CustomerSummary customer = customerService.getSummary(order.getCustomerId());
                yield ResponseEntity.ok(OrderResponseV2.from(order, customer));
            }
            default -> throw new UnsupportedApiVersionException(version);
        };
    }
}

// ===== Example: Evolving a DTO safely (non-breaking) =====
public record OrderResponseV1(
        String id,
        String customerId,
        BigDecimal totalAmount,
        String status,
        LocalDateTime createdAt,

        // SAFE: New optional field — existing consumers ignore it via @JsonIgnoreProperties
        @JsonInclude(JsonInclude.Include.NON_NULL)
        String trackingNumber,

        // SAFE: New optional field with default
        @JsonInclude(JsonInclude.Include.NON_NULL)
        ShippingEstimate shippingEstimate
) {}

// ===== Example: Breaking change that requires a new version =====

// V1: price as string (legacy mistake)
public record ProductResponseV1(
        String id,
        String name,
        String price  // "19.99" — string for historical reasons
) {}

// V2: price as structured Money object (BREAKING CHANGE)
public record ProductResponseV2(
        String id,
        String name,
        Money price  // { "amount": 19.99, "currency": "USD" } — proper type
) {}

@Configuration
public class GatewayVersionRoutingConfig {

    @Bean
    public RouteLocator versionedRoutes(RouteLocatorBuilder builder) {
        return builder.routes()
                // URI path versioning — route by path prefix
                .route("orders-v1", r -> r
                        .path("/api/v1/orders/**")
                        .filters(f -> f
                                .stripPrefix(2)  // remove /api/v1
                                .addRequestHeader("X-Routed-Version", "1")
                                .retry(config -> config.setRetries(3)))
                        .uri("lb://order-service"))

                .route("orders-v2", r -> r
                        .path("/api/v2/orders/**")
                        .filters(f -> f
                                .stripPrefix(2)  // remove /api/v2
                                .addRequestHeader("X-Routed-Version", "2")
                                .circuitBreaker(config -> config
                                        .setName("orders-v2-cb")
                                        .setFallbackUri("forward:/fallback/orders")))
                        .uri("lb://order-service"))

                // Header versioning — route by custom header
                .route("orders-header-v2", r -> r
                        .path("/api/orders/**")
                        .and()
                        .header("X-API-Version", "2")
                        .filters(f -> f.addRequestHeader("X-Routed-Version", "2"))
                        .uri("lb://order-service"))

                .build();
    }
}

@Component
public class DeprecationHeaderFilter implements GlobalFilter, Ordered {

    private static final Map<String, String> DEPRECATED_VERSIONS = Map.of(
            "v1", "2026-09-01"
    );

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        String path = exchange.getRequest().getPath().value();

        for (Map.Entry<String, String> entry : DEPRECATED_VERSIONS.entrySet()) {
            if (path.contains("/api/" + entry.getKey() + "/")) {
                exchange.getResponse().getHeaders().add("Sunset", entry.getValue());
                exchange.getResponse().getHeaders().add("Deprecation", "true");
                exchange.getResponse().getHeaders().add("Link",
                        "</api/v2/docs>; rel=\"successor-version\"");
            }
        }

        return chain.filter(exchange);
    }

    @Override
    public int getOrder() {
        return -1;
    }
}

@Component
public class SunsetHeaderInterceptor implements HandlerInterceptor {

    private final ApiVersionRegistry versionRegistry;

    public SunsetHeaderInterceptor(ApiVersionRegistry versionRegistry) {
        this.versionRegistry = versionRegistry;
    }

    @Override
    public void postHandle(HttpServletRequest request, HttpServletResponse response,
                           Object handler, ModelAndView modelAndView) {

        String version = extractVersion(request);
        VersionMetadata metadata = versionRegistry.getMetadata(version);

        if (metadata != null && metadata.isDeprecated()) {
            // RFC 8594 Sunset header
            response.setHeader("Sunset", metadata.getSunsetDate()
                    .format(DateTimeFormatter.RFC_1123_DATE_TIME));

            // Deprecation header (RFC draft)
            response.setHeader("Deprecation", metadata.getDeprecationDate()
                    .format(DateTimeFormatter.RFC_1123_DATE_TIME));

            // Link to successor version docs
            response.setHeader("Link",
                    String.format("<%s>; rel=\"successor-version\"", metadata.getSuccessorUrl()));

            // Warning header for intermediaries
            response.setHeader("Warning",
                    "299 - \"API version " + version + " is deprecated. " +
                    "Migrate to " + metadata.getSuccessorVersion() + " before " +
                    metadata.getSunsetDate() + "\"");
        }
    }

    private String extractVersion(HttpServletRequest request) {
        String path = request.getRequestURI();
        Matcher matcher = Pattern.compile("/api/(v\\d+)/").matcher(path);
        return matcher.find() ? matcher.group(1) : "v1";
    }
}

// ===== Version Registry for managing lifecycle =====
@Component
public class ApiVersionRegistry {

    private final Map<String, VersionMetadata> versions = Map.of(
            "v1", new VersionMetadata("v1", "v2",
                    LocalDate.of(2026, 3, 1),   // deprecated since
                    LocalDate.of(2026, 9, 1),   // sunset date
                    "/api/v2/docs",
                    true),
            "v2", new VersionMetadata("v2", null,
                    null, null,
                    "/api/v2/docs",
                    false),
            "v3", new VersionMetadata("v3", null,
                    null, null,
                    "/api/v3/docs",
                    false)
    );

    public VersionMetadata getMetadata(String version) {
        return versions.get(version);
    }
}

@Component
public class SunsetEnforcementFilter extends OncePerRequestFilter {

    private final ApiVersionRegistry versionRegistry;

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                     HttpServletResponse response,
                                     FilterChain filterChain) throws ServletException, IOException {

        String version = extractVersion(request);
        VersionMetadata metadata = versionRegistry.getMetadata(version);

        if (metadata != null && metadata.isPastSunset()) {
            response.setStatus(HttpStatus.GONE.value());
            response.setContentType(MediaType.APPLICATION_JSON_VALUE);
            response.getWriter().write("""
                {
                    "error": "GONE",
                    "message": "API version %s has been retired as of %s",
                    "migrationGuide": "%s",
                    "successorVersion": "%s"
                }
                """.formatted(version, metadata.getSunsetDate(),
                    metadata.getSuccessorUrl(), metadata.getSuccessorVersion()));
            return;
        }

        filterChain.doFilter(request, response);
    }
}