RESTful API Design Best Practices

// A resource designed by these rules, with the reasoning kept in the comments.
using System.Text.Json.Serialization;
using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllers().AddJsonOptions(o =>
{
    o.JsonSerializerOptions.PropertyNamingPolicy = System.Text.Json.JsonNamingPolicy.CamelCase;
    // Pick one and never change it: either always send nulls or never send them
    o.JsonSerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull;
    o.JsonSerializerOptions.Converters.Add(new JsonStringEnumConverter());
});
var app = builder.Build();
app.MapControllers();
app.Run();
// /api/purchase-orders : plural, lowercase, hyphenated
[ApiController]
[Route("api/purchase-orders")]
[Produces("application/json")]
public class PurchaseOrdersController : ControllerBase
{
    private readonly AppDbContext db;
    public PurchaseOrdersController(AppDbContext db) => this.db = db;
    // Filters live in the QUERY STRING, so one endpoint serves every combination.
    // Not /api/purchase-orders/status/pending/supplier/3
    [HttpGet]
    public async Task<ActionResult<PagedResult<OrderSummary>>> Search(
        [FromQuery] OrderStatus? status, [FromQuery] int? supplierId,
        [FromQuery] int page = 1, [FromQuery] int pageSize = 20, CancellationToken ct = default)
    {
        pageSize = Math.Clamp(pageSize, 1, 100);
        IQueryable<PurchaseOrder> query = db.PurchaseOrders.AsNoTracking();
        if (status is not null)     query = query.Where(o => o.Status == status);
        if (supplierId is not null) query = query.Where(o => o.SupplierId == supplierId);
        int total = await query.CountAsync(ct);
        List<OrderSummary> items = await query
            .OrderByDescending(o => o.PlacedAt).ThenBy(o => o.Id)
            .Skip((page - 1) * pageSize).Take(pageSize)
            .Select(o => new OrderSummary(o.Id, o.Reference, o.Status, o.Total, o.PlacedAt))
            .ToListAsync(ct);
        // No matches is 200 with an empty array. The collection exists; it is just empty.
        return new PagedResult<OrderSummary>(items, page, pageSize, total);
    }
    [HttpGet("{id:int}", Name = nameof(GetById))]
    public async Task<ActionResult<OrderDetail>> GetById(int id, CancellationToken ct)
    {
        OrderDetail? order = await db.PurchaseOrders
            .Where(o => o.Id == id)
            .Select(o => new OrderDetail(
                o.Id, o.Reference, o.Status, o.Total, o.PlacedAt,
                // An empty array, never null. The client can loop without a null check.
                o.Lines.Select(l => new LineItem(l.Sku, l.Quantity, l.UnitPrice)).ToList()))
            .FirstOrDefaultAsync(ct);
        return order is null ? NotFound() : order;
    }
    // One level of nesting shows ownership. Deeper than this and you should
    // address the child directly at /api/order-lines/{id}.
    [HttpGet("{id:int}/lines")]
    public async Task<ActionResult<List<LineItem>>> GetLines(int id, CancellationToken ct) =>
        await db.OrderLines.Where(l => l.PurchaseOrderId == id)
            .Select(l => new LineItem(l.Sku, l.Quantity, l.UnitPrice))
            .ToListAsync(ct);
    // POST with an Idempotency-Key. A retried request after a dropped connection
    // returns the ORIGINAL order instead of creating a second one.
    // Any endpoint that costs money should do this.
    [HttpPost]
    public async Task<ActionResult<OrderDetail>> Create(
        [FromBody] CreateOrderRequest request,
        [FromHeader(Name = "Idempotency-Key")] string? idempotencyKey,
        CancellationToken ct)
    {
        if (!string.IsNullOrWhiteSpace(idempotencyKey))
        {
            PurchaseOrder? existing = await db.PurchaseOrders
                .FirstOrDefaultAsync(o => o.IdempotencyKey == idempotencyKey, ct);
            if (existing is not null)
                return Ok(ToDetail(existing));      // same answer, no duplicate
        }
        var order = new PurchaseOrder
        {
            Reference       = $"PO-{DateTime.UtcNow:yyyyMMdd}-{Random.Shared.Next(1000, 9999)}",
            SupplierId      = request.SupplierId,
            Status          = OrderStatus.Draft,
            PlacedAt        = DateTime.UtcNow,       // UTC, always
            IdempotencyKey  = idempotencyKey,
            Lines = request.Lines
                .Select(l => new OrderLine { Sku = l.Sku, Quantity = l.Quantity, UnitPrice = l.UnitPrice })
                .ToList()
        };
        order.Total = order.Lines.Sum(l => l.Quantity * l.UnitPrice);
        db.PurchaseOrders.Add(order);
        await db.SaveChangesAsync(ct);
        // 201, a Location header, and the created object so the client has the id
        return CreatedAtRoute(nameof(GetById), new { id = order.Id }, ToDetail(order));
    }
    // An action that is not CRUD, option A: PATCH the state field. The most RESTful.
    [HttpPatch("{id:int}")]
    public async Task<IActionResult> Patch(int id, [FromBody] PatchOrderRequest patch, CancellationToken ct)
    {
        PurchaseOrder? order = await db.PurchaseOrders.FindAsync(new object[] { id }, ct);
        if (order is null) return NotFound();
        if (patch.Status is not null) order.Status = patch.Status.Value;   // null means leave alone
        await db.SaveChangesAsync(ct);
        return NoContent();
    }
    // Option B: POST to a sub resource. Less pure, more practical, very common.
    // Pick one style and use it everywhere.
    [HttpPost("{id:int}/cancel")]
    public async Task<IActionResult> Cancel(int id, [FromBody] CancelRequest request, CancellationToken ct)
    {
        PurchaseOrder? order = await db.PurchaseOrders.FindAsync(new object[] { id }, ct);
        if (order is null) return NotFound();
        if (order.Status == OrderStatus.Shipped)
            // 409, not 400: the request is valid, the current STATE forbids it
            return Conflict(new ProblemDetails
            {
                Type   = "https://api.example.com/errors/order-already-shipped",
                Title  = "Order already shipped",
                Status = StatusCodes.Status409Conflict,
                Detail = $"Order {order.Reference} shipped on {order.ShippedOn:yyyy-MM-dd} and cannot be cancelled."
            });
        order.Status = OrderStatus.Cancelled;
        await db.SaveChangesAsync(ct);
        return NoContent();
    }
    [HttpDelete("{id:int}")]
    public async Task<IActionResult> Delete(int id, CancellationToken ct)
    {
        PurchaseOrder? order = await db.PurchaseOrders.FindAsync(new object[] { id }, ct);
        if (order is null) return NotFound();
        db.PurchaseOrders.Remove(order);
        await db.SaveChangesAsync(ct);
        return NoContent();
    }
    private static OrderDetail ToDetail(PurchaseOrder o) => new(
        o.Id, o.Reference, o.Status, o.Total, o.PlacedAt,
        o.Lines.Select(l => new LineItem(l.Sku, l.Quantity, l.UnitPrice)).ToList());
}
public enum OrderStatus { Draft, Submitted, Shipped, Cancelled }
// Dates are UTC DateTime and serialize as "2026-09-07T16:40:00Z".
// A date with no time uses DateOnly and serializes as "2026-09-07".
public record OrderSummary(int Id, string Reference, OrderStatus Status, decimal Total, DateTime PlacedAt);
public record OrderDetail(int Id, string Reference, OrderStatus Status, decimal Total,
                          DateTime PlacedAt, List<LineItem> Lines);
public record LineItem(string Sku, int Quantity, decimal UnitPrice);
public record CreateOrderRequest(int SupplierId, List<LineItem> Lines);
public record PatchOrderRequest(OrderStatus? Status);
public record CancelRequest(string? Reason);
public record PagedResult<T>(IReadOnlyList<T> Items, int Page, int PageSize, int TotalCount);
public class PurchaseOrder
{
    public int Id { get; set; }
    public string Reference { get; set; } = "";
    public int SupplierId { get; set; }
    public OrderStatus Status { get; set; }
    public decimal Total { get; set; }
    public DateTime PlacedAt { get; set; }
    public DateOnly? ShippedOn { get; set; }
    public string? IdempotencyKey { get; set; }
    public List<OrderLine> Lines { get; set; } = new();
}
public class OrderLine
{
    public int Id { get; set; }
    public int PurchaseOrderId { get; set; }
    public string Sku { get; set; } = "";
    public int Quantity { get; set; }
    public decimal UnitPrice { get; set; }
}
public class AppDbContext : DbContext
{
    public AppDbContext(DbContextOptions<AppDbContext> o) : base(o) { }
    public DbSet<PurchaseOrder> PurchaseOrders => Set<PurchaseOrder>();
    public DbSet<OrderLine> OrderLines => Set<OrderLine>();
    protected override void OnModelCreating(ModelBuilder b) =>
        b.Entity<PurchaseOrder>().HasIndex(o => o.IdempotencyKey).IsUnique();
}