REST Rules Senior Devs Follow (That Juniors Don't)

❌  GET  /api/getOrders
❌  POST /api/createOrder
❌  POST /api/deleteOrder/5
❌  GET  /api/order/fetchById?id=5

✅  GET    /api/orders
✅  POST   /api/orders
✅  DELETE /api/orders/5
✅  GET    /api/orders/5

[ApiController]
[Route("api/orders")]
public class OrdersController : ControllerBase
{
    [HttpGet]          // GET  /api/orders
    [HttpGet("{id}")]  // GET  /api/orders/5
    [HttpPost]         // POST /api/orders
    [HttpPut("{id}")]  // PUT  /api/orders/5
    [HttpDelete("{id}")] // DELETE /api/orders/5
}

✅  GET /api/orders/5/items          → items belonging to order 5
✅  GET /api/orders/5/items/12       → item 12 of order 5
❌  GET /api/orders/5/items/12/tags/7/categories  → too deep, just use query params

// PUT — replace the whole order (client sends all fields)
[HttpPut("{id}")]
public async Task<IActionResult> Replace(int id, ReplaceOrderDto dto, CancellationToken ct)
{
    // dto must contain every field — missing fields = null/default
}

// PATCH — update only what the client sends
[HttpPatch("{id}")]
public async Task<IActionResult> Update(int id, JsonPatchDocument<UpdateOrderDto> patch, CancellationToken ct)
{
    var order = await _db.Orders.FindAsync(id, ct) ?? return NotFound();
    var dto = mapper.Map<UpdateOrderDto>(order);
    patch.ApplyTo(dto, ModelState);
    if (!ModelState.IsValid) return ValidationProblem(ModelState);
    mapper.Map(dto, order);
    await _db.SaveChangesAsync(ct);
    return NoContent();
}

// ❌ Junior: 200 for everything
[HttpPost]
public IActionResult Create(CreateOrderDto dto)
{
    var order = service.Create(dto);
    return Ok(order);  // 200 — wrong for creation
}

// ✅ Senior: correct status codes
[HttpPost]
public async Task<IActionResult> Create(CreateOrderDto dto, CancellationToken ct)
{
    var order = await _orderService.CreateAsync(dto, ct);
    return CreatedAtAction(nameof(GetById), new { id = order.Id }, order);  // 201 + Location header
}

// Program.cs
builder.Services.AddProblemDetails();

// Global exception handler
app.UseExceptionHandler();

// Return ProblemDetails-shaped validation errors automatically
builder.Services.Configure<ApiBehaviorOptions>(options =>
    options.InvalidModelStateResponseFactory = ctx =>
    {
        var problem = ctx.HttpContext.RequestServices
            .GetRequiredService<ProblemDetailsFactory>()
            .CreateValidationProblemDetails(ctx.HttpContext, ctx.ModelState, 400);
        return new BadRequestObjectResult(problem);
    });

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
  "title": "Not Found",
  "status": 404,
  "detail": "Order 42 was not found.",
  "instance": "/api/orders/42",
  "traceId": "00-abc123..."
}

dotnet add package Asp.Versioning.Mvc
dotnet add package Asp.Versioning.Mvc.ApiExplorer

// Program.cs
builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;  // adds api-supported-versions header
    options.ApiVersionReader = ApiVersionReader.Combine(
        new UrlSegmentApiVersionReader(),      // /api/v1/orders
        new HeaderApiVersionReader("X-Api-Version") // header fallback
    );
});

[ApiController]
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/orders")]
public class OrdersV1Controller : ControllerBase { }

[ApiController]
[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/orders")]
public class OrdersV2Controller : ControllerBase { }

// Standard query params: ?page=1&pageSize=20&sortBy=createdAt&sortDir=desc&search=foo
public record PagedQuery(
    int Page = 1,
    int PageSize = 20,
    string? SortBy = null,
    string SortDir = "asc",
    string? Search = null
);

public record PagedResult<T>(
    IReadOnlyList<T> Items,
    int Page,
    int PageSize,
    int TotalCount,
    int TotalPages
);

[HttpGet]
public async Task<ActionResult<PagedResult<OrderSummaryDto>>> GetAll(
    [FromQuery] PagedQuery query, CancellationToken ct)
{
    var q = _db.Orders.AsNoTracking();

    if (!string.IsNullOrWhiteSpace(query.Search))
        q = q.Where(o => o.Reference.Contains(query.Search));

    var total = await q.CountAsync(ct);

    var items = await q
        .OrderBy(query.SortBy ?? "createdAt", query.SortDir)
        .Skip((query.Page - 1) * query.PageSize)
        .Take(Math.Min(query.PageSize, 100))   // hard cap at 100
        .Select(o => new OrderSummaryDto(o.Id, o.Reference, o.Status, o.TotalAmount))
        .ToListAsync(ct);

    return Ok(new PagedResult<OrderSummaryDto>(
        items, query.Page, query.PageSize, total,
        (int)Math.Ceiling((double)total / query.PageSize)
    ));
}

❌  GET /api/orders/1     → tells competitors you've had exactly 1 order
❌  GET /api/users/42     → tells bots exactly how many users you have

✅  GET /api/orders/b3f1a2c4-...   (GUID)
✅  GET /api/orders/ORD-2026-X7K2   (opaque reference)

public class Order
{
    public int Id { get; set; }               // internal PK — never exposed
    public Guid PublicId { get; set; } = Guid.NewGuid();  // exposed in API
    public string Reference { get; set; } = default!;     // human-readable
}

// Route uses PublicId, not Id
[HttpGet("{publicId:guid}")]
public async Task<ActionResult<OrderDetailDto>> GetById(Guid publicId, CancellationToken ct)
{
    var order = await _db.Orders
        .AsNoTracking()
        .FirstOrDefaultAsync(o => o.PublicId == publicId, ct)
        ?? return NotFound();
    // ...
}

// Use FluentValidation — not Data Annotations in a serious API
public class CreateOrderCommandValidator : AbstractValidator<CreateOrderCommand>
{
    public CreateOrderCommandValidator()
    {
        RuleFor(x => x.CustomerId).GreaterThan(0);
        RuleFor(x => x.DeliveryAddress).NotEmpty().MaximumLength(500);
        RuleFor(x => x.Items).NotEmpty().WithMessage("At least one item required.");
        RuleForEach(x => x.Items).ChildRules(item =>
        {
            item.RuleFor(i => i.ProductId).GreaterThan(0);
            item.RuleFor(i => i.Quantity).InclusiveBetween(1, 1000);
            item.RuleFor(i => i.UnitPrice).GreaterThan(0);
        });
    }
}

// ❌ Forces the client to make a second request to see what was created
[HttpPost]
public async Task<IActionResult> Create(CreateOrderDto dto)
{
    var id = await _service.CreateAsync(dto);
    return CreatedAtAction(nameof(GetById), new { id }, null);  // no body
}

// ✅ Client gets the resource immediately — includes server-assigned fields
[HttpPost]
public async Task<IActionResult> Create(CreateOrderDto dto, CancellationToken ct)
{
    var order = await _service.CreateAsync(dto, ct);
    return CreatedAtAction(
        nameof(GetById),
        new { id = order.PublicId },
        order  // return the full created resource
    );
}

✅ You can ADD new fields to a response — clients ignore what they don't know
✅ You can ADD new optional request fields — existing clients omit them
✅ You can ADD new endpoints
❌ Never REMOVE or RENAME a response field on an existing version
❌ Never make an optional request field REQUIRED on an existing version
❌ Never change the meaning of an existing field

GET    /api/orders          → list (paginated)
GET    /api/orders/{id}     → single
POST   /api/orders          → create → 201 + Location
PUT    /api/orders/{id}     → full replace → 200 or 204
PATCH  /api/orders/{id}     → partial update → 200 or 204
DELETE /api/orders/{id}     → remove → 204

Errors  → ProblemDetails (RFC 9457), never raw exceptions
IDs     → GUIDs or opaque refs in URLs, never auto-increment PKs
Pages   → ?page=1&pageSize=20, hard cap on pageSize
Versions → /api/v1/... from day one