Extending an Existing System via REST API Integration [With a Practical Example]

// GET: Orders
public async Task<IActionResult> Index()
{
    var orders = await _orderService.GetAllOrdersAsync();
    return View(orders);
}
 
// POST: Orders/Create
[HttpPost]
[ValidateAntiForgeryToken]
public async Task<IActionResult> Create(CreateOrderViewModel viewModel)
{
    if (ModelState.IsValid)
    {
        try
        {
            await _orderService.CreateOrderAsync(viewModel.Order);
            return RedirectToAction(nameof(Index));
        }
        catch (Exception ex)
        {
            ModelState.AddModelError("", "Unable to create order. Please try again.");
        }
    }
 
    viewModel.Customers = await _customerService.GetCustomerDropdownItemsAsync();
    viewModel.Products = await _productService.GetProductDropdownItemsAsync();
    return View(viewModel);
}

<table class="table table-hover" id="ordersTable">
  <thead>
    <tr>
      <th>Order Number</th>
      <th>Customer</th>
      <th>Items</th>
      <th>Order Date</th>
      <th>Status</th>
      <th>Total</th>
      <th>Actions</th>
    </tr>
  </thead>
  <tbody>
    @foreach (var order in Model.OrderByDescending(o => o.OrderDate))
    {
      <tr data-status="@order.Status">
        <td>
          <a asp-action="Details" asp-route-id="@order.Id" class="text-decoration-none fw-bold">
            @order.OrderNumber
          </a>
        </td>
        <td>
          <div class="d-flex align-items-center">
            <div class="customer-avatar bg-primary text-white rounded-circle d-flex align-items-center justify-content-center me-2" style="width: 32px; height: 32px;">
              @(order.Customer?.FirstName.FirstOrDefault().ToString().ToUpper())
            </div>
            <div>
              <a asp-controller="Customers" asp-action="Details" asp-route-id="@order.CustomerId" class="text-decoration-none d-block">
                @($"{order.Customer?.FirstName} {order.Customer?.LastName}")
              </a>
              <small class="text-muted">
                @order.Customer?.Email
              </small>
            </div>
          </div>
        </td>
        <td>
          <span class="badge bg-secondary">
            @order.OrderItems.Count items
          </span>
        </td>
        <td>
          <div>@order.OrderDate.ToString("MMM d, yyyy")</div>
          <small class="text-muted">
            @order.OrderDate.ToString("HH:mm")
          </small>
        </td>
        <td>
          <span class="badge bg-@(order.Status switch {
                                OrderStatus.Pending => "warning",
                                OrderStatus.Processing => "info",
                                OrderStatus.Shipped => "primary",
                                OrderStatus.Delivered => "success",
                                OrderStatus.Cancelled => "danger",
                                _ => "secondary"
                            })">@order.Status</span>
        </td>
        <td>
          <div class="fw-bold">@order.TotalAmount.ToString("C")</div>
          <small class="text-muted">
            @order.OrderItems.Count item(s)
          </small>
        </td>
        <td>
          <div class="btn-group">
            <a asp-action="Details" asp-route-id="@order.Id" class="btn btn-sm btn-info" title="Details">
              <i class="bi bi-eye"></i> Details
            </a>
            <a asp-action="Edit" asp-route-id="@order.Id" class="btn btn-sm btn-primary" title="Edit">
              <i class="bi bi-pencil"></i> Edit
            </a>
            @if (order.Status != OrderStatus.Delivered && order.Status != OrderStatus.Cancelled)
            {
              <button type="button" class="btn btn-sm btn-danger" data-bs-toggle="modal" data-bs-target="#cancelModal" data-order-id="@order.Id" data-order-number="@order.OrderNumber">
                <i class="bi bi-x-circle"></i> Cancel
              </button>
            }
          </div>
        </td>
      </tr>
    }
  </tbody>
</table>

<form asp-action="Create" method="post" id="orderForm">

public class CreateOrderViewModel
{
    public OrderModel Order { get; set; } = new OrderModel();
    public IEnumerable<DropdownItem> Customers { get; set; } = [];
    public IEnumerable<DropdownItem> Products { get; set; } = [];
}

public async Task<IEnumerable<OrderModel>> GetAllOrdersAsync()
{
    return _mapper.Map<IEnumerable<OrderModel>>(await _orderRepository.GetAllAsync());
}
 
public async Task<OrderModel> CreateOrderAsync(OrderModel order)
{
    var customer = await _customerRepository.GetByIdAsync(order.CustomerId) 
        ?? throw new InvalidOperationException("Customer not found");
 
    foreach (var item in order.OrderItems)
    {
        var product = await _productRepository.GetByIdAsync(item.ProductId) 
            ?? throw new InvalidOperationException($"Product with ID {item.ProductId} not found");
        item.UnitPrice = product.Price;
    }
 
    order.OrderNumber = $"ORD-{DateTime.Now:yyyy-MM}-{order.Id:D3}";
    order.OrderDate = DateTime.Now;
    order.TotalAmount = order.OrderItems.Sum(item => item.UnitPrice * item.Quantity);
 
    return _mapper.Map<OrderModel>(await _orderRepository.CreateAsync(_mapper.Map<Order>(order)));
}

public async Task<IEnumerable<Order>> GetAllAsync()
{
    return [.. InMemoryDatabase.Orders];
}
 
public async Task<Order> CreateAsync(Order order)
 
{
    order.Id = InMemoryDatabase.Orders.Count > 0 ?
        InMemoryDatabase.Orders.Max(o => o.Id) + 1 : 1;
    order.Customer = InMemoryDatabase.Customers.FirstOrDefault(c => c.Id == order.CustomerId);
 
    foreach (var item in order.OrderItems)
    {
        item.Product = InMemoryDatabase.Products.FirstOrDefault(p => p.Id == item.ProductId);
    }
 
    InMemoryDatabase.Orders.Add(order);
    return order;
}

public class Order
{
     public int Id { get; set; }
     public string OrderNumber { get; set; } = string.Empty;
     public DateTime OrderDate { get; set; }
     public OrderStatus Status { get; set; }
     public decimal TotalAmount { get; set; }
     public int CustomerId { get; set; }
     public Customer Customer { get; set; } = new Customer();
     public List<OrderItem> OrderItems { get; set; } = [];
}

namespace OrderManagement.API.Controllers
{
    [ApiController]
    [Route("orders")]
    public class OrdersController : ControllerBase
    {
        private readonly IOrderService _orderService;
 
        public OrdersController(IOrderService orderService)
        {
            _orderService = orderService;
        }
 
        [HttpGet]
        public async Task<ActionResult<IEnumerable<OrderResponse>>> GetAll()
        {
            var orders = await _orderService.GetAllOrdersAsync();
            return Ok(orders.Select(MapToResponse));
        }
 
        [HttpGet("{orderId:int}")]
        public async Task<ActionResult<OrderResponse>> GetById(int orderId)
        {
            var order = await _orderService.GetOrderByIdAsync(orderId);
            if (order is null)
                return NotFound();
 
            return Ok(MapToResponse(order));
        }
 
        [HttpPost]
        public async Task<ActionResult<OrderResponse>> Create([FromBody] CreateOrderRequest request)
        {
            var model = new OrderModel
            {
                CustomerId = request.CustomerId,
                OrderItems = request.OrderItems.Select(i => new OrderItemModel
                {
                    ProductId = i.ProductId,
                    Quantity = i.Quantity
                }).ToList()
            };
 
            var created = await _orderService.CreateOrderAsync(model);
            return CreatedAtAction(nameof(GetById), new { orderId = created.Id }, MapToResponse(created));
        }
 
        [HttpPut("{orderId:int}")]
        public async Task<IActionResult> UpdateStatus(int orderId, [FromBody] UpdateOrderStatusRequest request)
        {
            var order = await _orderService.GetOrderByIdAsync(orderId);
            if (order is null)
                return NotFound();
 
            order.Status = request.Status;
            await _orderService.UpdateOrderAsync(order);
            return NoContent();
        }
 
        [HttpDelete("{orderId:int}")]
        public async Task<IActionResult> Cancel(int orderId)
        {
            var order = await _orderService.GetOrderByIdAsync(orderId);
            if (order is null)
                return NotFound();
 
            await _orderService.DeleteOrderAsync(orderId);
            return NoContent();
        }
 
        private static OrderResponse MapToResponse(OrderModel order) => new()
        {
            Id = order.Id,
            OrderNumber = order.OrderNumber,
            CustomerId = order.CustomerId,
            CustomerName = order.CustomerName,
            OrderDate = order.OrderDate,
            Status = order.Status,
            TotalAmount = order.TotalAmount,
            OrderItems = order.OrderItems.Select(i => new OrderItemResponse
            {
                Id = i.Id,
                ProductId = i.ProductId,
                ProductName = i.ProductName,
                Quantity = i.Quantity,
                UnitPrice = i.UnitPrice,
                Total = i.Total
            }).ToList()
        };
    }
}

namespace OrderManagement.API.DTOs
{
    public class CreateOrderRequest
    {
        public int CustomerId { get; set; }
        public List<OrderItemRequest> OrderItems { get; set; } = new();
    }
}

using OrderManagement.Core.Interfaces;
using OrderManagement.Core.Mapping;
using OrderManagement.Core.Services;
using OrderManagement.Data.Interfaces;
using OrderManagement.Data.Repositories;
 
var builder = WebApplication.CreateBuilder(args);
 
builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
 
// AutoMapper
builder.Services.AddAutoMapper(typeof(MappingProfile));
 
// Repositories (singleton for in-memory storage)
builder.Services.AddSingleton<ICustomerRepository, CustomerRepository>();
builder.Services.AddSingleton<IProductRepository, ProductRepository>();
builder.Services.AddSingleton<IOrderRepository, OrderRepository>();
 
// Services
builder.Services.AddScoped<ICustomerService, CustomerService>();
builder.Services.AddScoped<IProductService, ProductService>();
builder.Services.AddScoped<IOrderService, OrderService>();
 
var app = builder.Build();
 
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}
 
app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();
 
app.Run();

using Asp.Versioning;
using Microsoft.AspNetCore.Mvc;
using OrderManagement.API.DTOs;
using OrderManagement.Core.Interfaces;
using OrderManagement.Core.Models;
 
namespace OrderManagement.API.Controllers.V1
{
    [ApiController]
    [ApiVersion("1.0")]
    [Route("v{version:apiVersion}/orders")]
    [Tags("Orders (v1 — deprecated)")]
    public class OrdersController : ControllerBase
    {
        private readonly IOrderService _orderService;
 
        public OrdersController(IOrderService orderService)
        {
            _orderService = orderService;
        }
 
        /// <summary>Returns all orders.</summary>
        [HttpGet]
        [ProducesResponseType(typeof(IEnumerable<OrderResponse>), StatusCodes.Status200OK)]
        public async Task<ActionResult<IEnumerable<OrderResponse>>> GetAll()
        {
            var orders = await _orderService.GetAllOrdersAsync();
            return Ok(orders.Select(MapToResponse));
        }
 
        /// <summary>Returns a single order by ID.</summary>
        [HttpGet("{orderId:int}")]
        [ProducesResponseType(typeof(OrderResponse), StatusCodes.Status200OK)]
        [ProducesResponseType(StatusCodes.Status404NotFound)]
        public async Task<ActionResult<OrderResponse>> GetById(int orderId)
        {
            var order = await _orderService.GetOrderByIdAsync(orderId);
            if (order is null)
                return NotFound();
 
            return Ok(MapToResponse(order));
        }
 
        /// <summary>Creates a new order.</summary>
        [HttpPost]
        [ProducesResponseType(typeof(OrderResponse), StatusCodes.Status201Created)]
        public async Task<ActionResult<OrderResponse>> Create([FromBody] CreateOrderRequest request)
        {
            var model = new OrderModel
            {
                CustomerId = request.CustomerId,
                OrderItems = request.OrderItems.Select(i => new OrderItemModel
                {
                    ProductId = i.ProductId,
                    Quantity = i.Quantity
                }).ToList()
            };
 
            var created = await _orderService.CreateOrderAsync(model);
            return CreatedAtAction(nameof(GetById), new { orderId = created.Id }, MapToResponse(created));
        }
 
        /// <summary>Updates the status of an order.</summary>
        [HttpPut("{orderId:int}")]
        [ProducesResponseType(StatusCodes.Status204NoContent)]
        [ProducesResponseType(StatusCodes.Status404NotFound)]
        public async Task<IActionResult> UpdateStatus(int orderId, [FromBody] UpdateOrderStatusRequest request)
        {
            var order = await _orderService.GetOrderByIdAsync(orderId);
            if (order is null)
                return NotFound();
 
            order.Status = request.Status;
            await _orderService.UpdateOrderAsync(order);
            return NoContent();
        }
 
        /// <summary>Cancels (deletes) an order.</summary>
        [HttpDelete("{orderId:int}")]
        [ProducesResponseType(StatusCodes.Status204NoContent)]
        [ProducesResponseType(StatusCodes.Status404NotFound)]
        public async Task<IActionResult> Delete(int orderId)
        {
            var order = await _orderService.GetOrderByIdAsync(orderId);
            if (order is null)
                return NotFound();
 
            await _orderService.DeleteOrderAsync(orderId);
            return NoContent();
        }
 
        private static OrderResponse MapToResponse(OrderModel order) => new()
        {
            Id = order.Id,
            OrderNumber = order.OrderNumber,
            CustomerId = order.CustomerId,
            CustomerName = order.CustomerName,
            OrderDate = order.OrderDate,
            Status = order.Status,
            TotalAmount = order.TotalAmount,
            OrderItems = order.OrderItems.Select(i => new OrderItemResponse
            {
                Id = i.Id,
                ProductId = i.ProductId,
                ProductName = i.ProductName,
                Quantity = i.Quantity,
                UnitPrice = i.UnitPrice,
                Total = i.Total
            }).ToList()
        };
    }
}

using Asp.Versioning;
using Microsoft.AspNetCore.Mvc;
using OrderManagement.API.DTOs;
using OrderManagement.API.DTOs.V2;
using OrderManagement.Core.Interfaces;
using OrderManagement.Core.Models;
 
namespace OrderManagement.API.Controllers.V2
{
    [ApiController]
    [ApiVersion("2.0")]
    [Route("v{version:apiVersion}/orders")]
    [Tags("Orders (v2)")]
    public class OrdersController : ControllerBase
    {
        private readonly IOrderService _orderService;
 
        public OrdersController(IOrderService orderService)
        {
            _orderService = orderService;
        }
 
        /// <summary>
        /// Returns all orders with optional status filtering and pagination.
        /// Pagination metadata is returned via <c>X-Total-Count</c>, <c>X-Page</c>, and <c>X-Page-Size</c> response headers.
        /// </summary>
        [HttpGet]
        [ProducesResponseType(typeof(IEnumerable<OrderResponseV2>), StatusCodes.Status200OK)]
        public async Task<ActionResult<IEnumerable<OrderResponseV2>>> GetAll(
            [FromQuery] OrderStatus? status,
            [FromQuery] int page = 1,
            [FromQuery] int pageSize = 20)
        {
            var orders = await _orderService.GetAllOrdersAsync();
            var filtered = orders.AsEnumerable();
 
            if (status.HasValue)
                filtered = filtered.Where(o => o.Status == status.Value);
 
            var total = filtered.Count();
            var paged = filtered.Skip((page - 1) * pageSize).Take(pageSize);
 
            Response.Headers["X-Total-Count"] = total.ToString();
            Response.Headers["X-Page"] = page.ToString();
            Response.Headers["X-Page-Size"] = pageSize.ToString();
 
            return Ok(paged.Select(MapToResponse));
        }
 
        /// <summary>Returns a single order by ID.</summary>
        [HttpGet("{orderId:int}")]
        [ProducesResponseType(typeof(OrderResponseV2), StatusCodes.Status200OK)]
        [ProducesResponseType(StatusCodes.Status404NotFound)]
        public async Task<ActionResult<OrderResponseV2>> GetById(int orderId)
        {
            var order = await _orderService.GetOrderByIdAsync(orderId);
            if (order is null)
                return NotFound();
 
            return Ok(MapToResponse(order));
        }
 
        /// <summary>Creates a new order.</summary>
        [HttpPost]
        [ProducesResponseType(typeof(OrderResponseV2), StatusCodes.Status201Created)]
        public async Task<ActionResult<OrderResponseV2>> Create([FromBody] CreateOrderRequest request)
        {
            var model = new OrderModel
            {
                CustomerId = request.CustomerId,
                OrderItems = request.OrderItems.Select(i => new OrderItemModel
                {
                    ProductId = i.ProductId,
                    Quantity = i.Quantity
                }).ToList()
            };
 
            var created = await _orderService.CreateOrderAsync(model);
            return CreatedAtAction(nameof(GetById), new { orderId = created.Id }, MapToResponse(created));
        }
 
        /// <summary>Updates the status of an order.</summary>
        [HttpPut("{orderId:int}")]
        [ProducesResponseType(StatusCodes.Status204NoContent)]
        [ProducesResponseType(StatusCodes.Status404NotFound)]
        public async Task<IActionResult> UpdateStatus(int orderId, [FromBody] UpdateOrderStatusRequest request)
        {
            var order = await _orderService.GetOrderByIdAsync(orderId);
            if (order is null)
                return NotFound();
 
            order.Status = request.Status;
            await _orderService.UpdateOrderAsync(order);
            return NoContent();
        }
 
        /// <summary>Cancels (deletes) an order.</summary>
        [HttpDelete("{orderId:int}")]
        [ProducesResponseType(StatusCodes.Status204NoContent)]
        [ProducesResponseType(StatusCodes.Status404NotFound)]
        public async Task<IActionResult> Delete(int orderId)
        {
            var order = await _orderService.GetOrderByIdAsync(orderId);
            if (order is null)
                return NotFound();
 
            await _orderService.DeleteOrderAsync(orderId);
            return NoContent();
        }
 
        private static OrderResponseV2 MapToResponse(OrderModel order) => new()
        {
            Id = order.Id,
            OrderNumber = order.OrderNumber,
            CustomerId = order.CustomerId,
            CustomerName = order.CustomerName,
            OrderDate = order.OrderDate,
            Status = order.Status,
            TotalAmount = order.TotalAmount,
            ItemCount = order.OrderItems.Count,
            OrderItems = order.OrderItems.Select(i => new OrderItemResponse
            {
                Id = i.Id,
                ProductId = i.ProductId,
                ProductName = i.ProductName,
                Quantity = i.Quantity,
                UnitPrice = i.UnitPrice,
                Total = i.Total
            }).ToList()
        };
    }
}

using OrderManagement.Core.Models;
 
namespace OrderManagement.API.DTOs.V2
{
    /// <summary>
    /// Extended order response introduced in V2.
    /// Adds <see cref="ItemCount"/> to the V1 payload.
    /// </summary>
    public class OrderResponseV2
    {
        public int Id { get; set; }
        public string OrderNumber { get; set; } = string.Empty;
        public int CustomerId { get; set; }
        public string CustomerName { get; set; } = string.Empty;
        public DateTime OrderDate { get; set; }
        public OrderStatus Status { get; set; }
        public decimal TotalAmount { get; set; }
 
        /// <summary>Total number of line items in this order. New in V2.</summary>
        public int ItemCount { get; set; }
 
        public List<OrderItemResponse> OrderItems { get; set; } = new();
    }
}

using Microsoft.OpenApi.Any;
using Microsoft.OpenApi.Models;
using OrderManagement.API.Versioning;
using Swashbuckle.AspNetCore.SwaggerGen;
 
namespace OrderManagement.API.Swagger
{
    public class ApiVersionHeaderOperationFilter : IOperationFilter
    {
        public void Apply(OpenApiOperation operation, OperationFilterContext context)
        {
            var groupName = context.ApiDescription.GroupName;
            if (string.IsNullOrEmpty(groupName))
                return;
 
            var isV1 = groupName.StartsWith("v1", StringComparison.OrdinalIgnoreCase);
            var supportedVersions = isV1
                ? ApiVersionConstants.V1SupportedMinorVersions
                : ApiVersionConstants.V2SupportedMinorVersions;
            var defaultVersion = isV1
                ? ApiVersionConstants.V1Default
                : ApiVersionConstants.V2Default;
 
            operation.Parameters ??= [];
            operation.Parameters.Add(new OpenApiParameter
            {
                Name = ApiVersionConstants.HeaderName,
                In = ParameterLocation.Header,
                Required = false,
                Schema = new OpenApiSchema
                {
                    Type = "string",
                    Enum = supportedVersions.Select(v => (IOpenApiAny)new OpenApiString(v)).ToList(),
                    Default = new OpenApiString(defaultVersion)
                },
                Description = $"Minor version in MAJOR.MINOR.PATCH format. Supported: {string.Join(", ", supportedVersions)}. Defaults to `{defaultVersion}`."
            });
        }
    }
}

using Asp.Versioning.ApiExplorer;
using Microsoft.Extensions.Options;
using Microsoft.OpenApi.Models;
using OrderManagement.API.Versioning;
using Swashbuckle.AspNetCore.SwaggerGen;
 
namespace OrderManagement.API.Swagger
{
    public class ConfigureSwaggerOptions : IConfigureOptions<SwaggerGenOptions>
    {
        private readonly IApiVersionDescriptionProvider _provider;
 
        public ConfigureSwaggerOptions(IApiVersionDescriptionProvider provider)
        {
            _provider = provider;
        }
 
        public void Configure(SwaggerGenOptions options)
        {
            foreach (var description in _provider.ApiVersionDescriptions)
            {
                options.SwaggerDoc(description.GroupName, CreateInfoForApiVersion(description));
            }
        }
 
        private static OpenApiInfo CreateInfoForApiVersion(ApiVersionDescription description)
        {
            var major = description.ApiVersion.MajorVersion;
 
            return new OpenApiInfo
            {
                Title = "Order Management API",
                Version = description.ApiVersion.ToString(),
                Description = BuildDescription(major, description.IsDeprecated),
                Contact = new OpenApiContact
                {
                    Name = "API Support",
                    Email = "api-support@example.com"
                }
            };
        }
 
        private static string BuildDescription(int? major, bool isDeprecated)
        {
            var deprecationBadge = isDeprecated ? " **⚠️ DEPRECATED**" : string.Empty;
 
            return major switch
            {
                1 => $"""
                      ### V1 — Basic CRUD{deprecationBadge}
 
                      This version is **deprecated** and will be sunset on `{ApiVersionConstants.V1SunsetDate}`.
                      Please migrate to V2 as soon as possible.
 
                      **Minor versions (`{ApiVersionConstants.HeaderName}` header):** {string.Join(", ", ApiVersionConstants.V1SupportedMinorVersions)}
                      - `1.0.0` — initial release
                      - `1.1.0` — bug-fix release (current V1 default)
 
                      ---
                      #### Migration from V1 to V2
                      | Change | V1 | V2 |
                      |--------|----|----|
                      | Base URL | `/v1/orders` | `/v2/orders` |
                      | `X-API-Version` | `1.x.x` | `2.x.x` |
                      | Response: `itemCount` | ❌ | ✅ |
                      | Filtering by status | ❌ | `?status=Pending` |
                      | Pagination | ❌ | `?page=1&pageSize=20` |
                      | Pagination headers | ❌ | `X-Total-Count`, `X-Page`, `X-Page-Size` |
 
                      To roll back to V1 during transition: point the base URL back to `/v1/` and set `{ApiVersionConstants.HeaderName}: 1.1.0`.
                      """,
 
                2 => $"""
                      ### V2 — Enhanced Orders ✅ Current stable version
 
                      **Minor versions (`{ApiVersionConstants.HeaderName}` header):** {string.Join(", ", ApiVersionConstants.V2SupportedMinorVersions)}
                      - `2.0.0` — initial V2 release with filtering and pagination
                      - `2.1.0` — extended pagination headers (current V2 default)
 
                      **New in V2 compared to V1:**
                      - `GET /v2/orders` supports `?status=` query filter
                      - `GET /v2/orders` supports `?page=` and `?pageSize=` for pagination
                      - Order response includes `itemCount` field
                      - Pagination metadata returned via `X-Total-Count`, `X-Page`, `X-Page-Size` headers
                      """,
 
                _ => string.Empty
            };
        }
    }
}

namespace OrderManagement.API.Versioning
{
    public static class ApiVersionConstants
    {
        public const string HeaderName = "X-API-Version";
 
        // V1 minor versions — receives bug fixes only, new features go to V2
        public const string V1Default = "1.1.0";
        public static readonly string[] V1SupportedMinorVersions = ["1.0.0", "1.1.0"];
 
        // V2 minor versions — current, actively developed version
        public const string V2Default = "2.1.0";
        public static readonly string[] V2SupportedMinorVersions = ["2.0.0", "2.1.0"];
 
        // RFC 8594 Sunset header value (HTTP-date format)
        public const string V1SunsetDate = "Thu, 01 Jan 2026 00:00:00 GMT";
    }
}

namespace OrderManagement.API.Versioning
{
    public class ApiVersionHeaderMiddleware
    {
        private readonly RequestDelegate _next;
 
        public ApiVersionHeaderMiddleware(RequestDelegate next)
        {
            _next = next;
        }
 
        public async Task InvokeAsync(HttpContext context)
        {
            var urlMajorVersion = ExtractMajorVersionFromPath(context.Request.Path);
 
            if (urlMajorVersion.HasValue)
            {
                var supportedMinorVersions = urlMajorVersion == 1
                    ? ApiVersionConstants.V1SupportedMinorVersions
                    : ApiVersionConstants.V2SupportedMinorVersions;
 
                var defaultMinorVersion = urlMajorVersion == 1
                    ? ApiVersionConstants.V1Default
                    : ApiVersionConstants.V2Default;
 
                if (context.Request.Headers.TryGetValue(ApiVersionConstants.HeaderName, out var headerValue)
                    && !string.IsNullOrWhiteSpace(headerValue))
                {
                    var versionString = headerValue.ToString();
 
                    if (!TryParseVersion(versionString, out var headerMajor))
                    {
                        context.Response.StatusCode = StatusCodes.Status400BadRequest;
                        await context.Response.WriteAsJsonAsync(new
                        {
                            error = $"Invalid '{ApiVersionConstants.HeaderName}' format. Expected MAJOR.MINOR.PATCH (e.g., '1.0.0')."
                        });
                        return;
                    }
 
                    if (headerMajor != urlMajorVersion.Value)
                    {
                        context.Response.StatusCode = StatusCodes.Status400BadRequest;
                        await context.Response.WriteAsJsonAsync(new
                        {
                            error = $"'{ApiVersionConstants.HeaderName}' major version ({headerMajor}) does not match URL major version ({urlMajorVersion.Value})."
                        });
                        return;
                    }
 
                    if (!supportedMinorVersions.Contains(versionString))
                    {
                        context.Response.StatusCode = StatusCodes.Status400BadRequest;
                        await context.Response.WriteAsJsonAsync(new
                        {
                            error = $"Version '{versionString}' is not supported. Supported: {string.Join(", ", supportedMinorVersions)}."
                        });
                        return;
                    }
 
                    context.Items[ApiVersionConstants.HeaderName] = versionString;
                }
                else
                {
                    context.Items[ApiVersionConstants.HeaderName] = defaultMinorVersion;
                }
 
                context.Items["UrlMajorVersion"] = urlMajorVersion.Value;
            }
 
            context.Response.OnStarting(() =>
            {
                if (context.Items.TryGetValue("UrlMajorVersion", out var majorObj) && majorObj is int major && major == 1)
                {
                    context.Response.Headers.Append("Deprecation", "true");
                    context.Response.Headers.Append("Sunset", ApiVersionConstants.V1SunsetDate);
                    context.Response.Headers.Append("Link", "</v2/orders>; rel=\"successor-version\"");
                }
 
                if (context.Items.TryGetValue(ApiVersionConstants.HeaderName, out var version) && version is string versionValue)
                {
                    context.Response.Headers[ApiVersionConstants.HeaderName] = versionValue;
                }
 
                return Task.CompletedTask;
            });
 
            await _next(context);
        }
 
        private static int? ExtractMajorVersionFromPath(PathString path)
        {
            var segments = path.Value?.Split('/', StringSplitOptions.RemoveEmptyEntries);
            if (segments is { Length: > 0 }
                && segments[0].StartsWith('v')
                && int.TryParse(segments[0][1..], out var major))
            {
                return major;
            }
            return null;
        }
 
        private static bool TryParseVersion(string value, out int major)
        {
            major = 0;
            var parts = value.Split('.');
            if (parts.Length != 3) return false;
            if (!int.TryParse(parts[0], out major)) return false;
            if (!int.TryParse(parts[1], out _)) return false;
            if (!int.TryParse(parts[2], out _)) return false;
            return true;
        }
    }
}

using Asp.Versioning;
using Microsoft.Extensions.Options;
using OrderManagement.API.Swagger;
using OrderManagement.API.Versioning;
using OrderManagement.Core.Interfaces;
using OrderManagement.Core.Mapping;
using OrderManagement.Core.Services;
using OrderManagement.Data.Interfaces;
using OrderManagement.Data.Repositories;
using Swashbuckle.AspNetCore.SwaggerGen;
 
var builder = WebApplication.CreateBuilder(args);
 
builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
 
// API Versioning — major versions via URL (/v1/, /v2/), minor versions via X-API-Version header
builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(2, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
    options.ApiVersionReader = new UrlSegmentApiVersionReader();
}).AddApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV";
    options.SubstituteApiVersionInUrl = true;
});
 
// Swagger — one document per major version
builder.Services.AddTransient<IConfigureOptions<SwaggerGenOptions>, ConfigureSwaggerOptions>();
builder.Services.AddSwaggerGen(options =>
{
    options.OperationFilter<ApiVersionHeaderOperationFilter>();
});
 
// AutoMapper
builder.Services.AddAutoMapper(typeof(MappingProfile));
 
// Repositories (singleton for in-memory storage)
builder.Services.AddSingleton<ICustomerRepository, CustomerRepository>();
builder.Services.AddSingleton<IProductRepository, ProductRepository>();
builder.Services.AddSingleton<IOrderRepository, OrderRepository>();
 
// Services
builder.Services.AddScoped<ICustomerService, CustomerService>();
builder.Services.AddScoped<IProductService, ProductService>();
builder.Services.AddScoped<IOrderService, OrderService>();
 
var app = builder.Build();
 
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI(options =>
    {
        foreach (var description in app.DescribeApiVersions())
        {
            options.SwaggerEndpoint(
                $"/swagger/{description.GroupName}/swagger.json",
                $"Order Management API {description.GroupName.ToUpperInvariant()}");
        }
    });
}
 
app.UseHttpsRedirection();
app.UseMiddleware<ApiVersionHeaderMiddleware>();
app.UseAuthorization();
app.MapControllers();
 
app.Run();

// Configure API
var jwtSettings = new JwtSettings
{
    Key = "your_very_long_secret_key_at_least_32_chars",
    Issuer = "your_issuer",
    Audience = "your_audience",
    ExpirationInMinutes = 60
};
 
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidateLifetime = true,
            ValidateIssuerSigningKey = true,
            ValidIssuer = jwtSettings.Issuer,
            ValidAudience = jwtSettings.Audience,
            IssuerSigningKey = new SymmetricSecurityKey(
                Encoding.UTF8.GetBytes(jwtSettings.Key))
        };
    });

// Authenticate user in a special Auth controller and provide JWT
[ApiController]
[Route("[controller]")]
public class AuthController : ControllerBase
{
    private readonly JwtSettings _jwtSettings;
    public AuthController(JwtSettings jwtSettings)
    {
        _jwtSettings = jwtSettings;
    }
 
    [HttpPost("login")]
    public IActionResult Login([FromBody] LoginModel model)
    {
        // Credentials check
        if (model.Username != "test" || model.Password != "test123")
            return Unauthorized();
 
        var token = GenerateJwtToken(model.Username);
        return Ok(new { token });
    }
 
    private string GenerateJwtToken(string username)
    {
        var securityKey = new SymmetricSecurityKey(
            Encoding.UTF8.GetBytes(_jwtSettings.Key));
 
        var credentials = new SigningCredentials(
            securityKey, SecurityAlgorithms.HmacSha256);
 
        var claims = new[]
        {
            new Claim(ClaimTypes.Name, username),
            new Claim(ClaimTypes.Role, "User"),
            new Claim(JwtRegisteredClaimNames.Jti, Guid.NewGuid().ToString())
        };
 
        var token = new JwtSecurityToken(
            issuer: _jwtSettings.Issuer,
            audience: _jwtSettings.Audience,
            claims: claims,
            expires: DateTime.Now.AddMinutes(_jwtSettings.ExpirationInMinutes),
            signingCredentials: credentials
        );
 
        return new JwtSecurityTokenHandler().WriteToken(token);
    }
}

[Authorize]
[ApiController]
[Route("[controller]")]
public class OrdersController ...