REST API Design Interview Questions for Senior Engineers

app.MapPost("/api/orders", async Task<Results<Created<OrderDto>, ProblemHttpResult>> (
    [FromHeader(Name = "Idempotency-Key")] string? idempotencyKey,
    CreateOrder command, ClaimsPrincipal user, ShopDbContext db, CancellationToken ct) =>
{
    if (!Guid.TryParse(idempotencyKey?.Trim('"'), out var key))
        return TypedResults.Problem(statusCode: 400, title: "Idempotency-Key header required.");

    var customerId = user.FindFirstValue(ClaimTypes.NameIdentifier)!;
    var existing = await db.Orders.AsNoTracking()
        .SingleOrDefaultAsync(o => o.CustomerId == customerId && o.IdempotencyKey == key, ct);

    if (existing is not null)
    {
        return existing.RequestHash == command.ComputeHash()
            ? TypedResults.Created($"/api/orders/{existing.Id}", existing.ToDto()) // Replay
            : TypedResults.Problem(statusCode: 422, title: "Idempotency-Key reused.");
    }

    var order = Order.Place(customerId, key, command);
    db.Orders.Add(order);
    await db.SaveChangesAsync(ct); // Unique index on (CustomerId, IdempotencyKey) catches races
    return TypedResults.Created($"/api/orders/{order.Id}", order.ToDto());
});

app.MapGet("/api/orders", async Task<Results<Ok<Page<OrderSummary>>, ProblemHttpResult>> (
    string? cursor, int? limit, ShopDbContext db, CancellationToken ct) =>
{
    var pageSize = Math.Clamp(limit ?? 25, 1, 100);
    IQueryable<Order> query = db.Orders.AsNoTracking();

    if (cursor is not null && OrderCursor.TryDecode(cursor, out var after))
    {
        query = query.Where(o => o.CreatedAt > after.CreatedAt
            || (o.CreatedAt == after.CreatedAt && o.Id > after.Id)); // Tiebreaker matters
    }

    var rows = await query.OrderBy(o => o.CreatedAt).ThenBy(o => o.Id)
        .Take(pageSize + 1) // One extra row reveals whether another page exists
        .Select(o => new OrderSummary(o.Id, o.CreatedAt, o.Total)).ToListAsync(ct);

    var hasMore = rows.Count > pageSize;
    var items = hasMore ? rows.GetRange(0, pageSize) : rows;
    var next = hasMore ? new OrderCursor(items[^1].CreatedAt, items[^1].Id).Encode() : null;
    return TypedResults.Ok(new Page<OrderSummary>(items, next));
});

public sealed class DomainExceptionHandler(IProblemDetailsService problemDetails) : IExceptionHandler
{
    public async ValueTask<bool> TryHandleAsync(
        HttpContext httpContext, Exception exception, CancellationToken cancellationToken)
    {
        var (status, type) = exception switch
        {
            ConflictException => (409, "https://api.contoso.com/problems/conflict"),
            BusinessRuleException => (422, "https://api.contoso.com/problems/business-rule"),
            _ => (0, null)
        };
        if (status == 0) return false; // Fall back to a generic 500

        httpContext.Response.StatusCode = status;
        return await problemDetails.TryWriteAsync(new ProblemDetailsContext
        {
            HttpContext = httpContext,
            Exception = exception,
            ProblemDetails = new() { Status = status, Type = type, Detail = exception.Message }
        });
    }
}

PATCH /orders/5f2b9c1e-8d7a-4f34-9b8e-2c1d0a6e7f10
Content-Type: application/json

{ "status": "Cancelled" }

app.MapPut("/api/products/{id:int}", async Task<IResult> (
    int id, UpdateProduct body, HttpContext http, ShopDbContext db, CancellationToken ct) =>
{
    var ifMatch = http.Request.GetTypedHeaders().IfMatch;
    if (ifMatch.Count == 0)
        return TypedResults.Problem(statusCode: 428, title: "Send If-Match with the ETag you last read.");

    var product = await db.Products.FindAsync([id], ct);
    if (product is null) return TypedResults.NotFound();

    var current = new EntityTagHeaderValue($"\"{Convert.ToHexString(product.Version)}\"");
    if (!ifMatch.Any(tag => tag.Equals(EntityTagHeaderValue.Any)
        || tag.Compare(current, useStrongComparison: true)))
        return TypedResults.Problem(statusCode: 412, title: "The product changed since you read it.");

    product.Update(body.Name, body.Price);
    await db.SaveChangesAsync(ct); // [Timestamp] Version guards the race after the check too

    http.Response.Headers.ETag = $"\"{Convert.ToHexString(product.Version)}\"";
    return TypedResults.NoContent();
});

using Asp.Versioning;

builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.ReportApiVersions = true; // Adds api-supported-versions / api-deprecated-versions
    options.ApiVersionReader = new UrlSegmentApiVersionReader();
});

var orders = app.NewVersionedApi("Orders");
orders.MapGroup("/api/v{version:apiVersion}/orders").HasApiVersion(2.0)
    .MapGet("/{id:guid}", OrderEndpointsV2.GetById);

app.MapPost("/api/reports", async (ReportRequest request, IReportJobs jobs, CancellationToken ct) =>
{
    var job = await jobs.EnqueueAsync(request, ct); // Validate first, then enqueue
    return TypedResults.Accepted($"/api/reports/jobs/{job.Id}", job);
});

app.MapGet("/api/reports/jobs/{id:guid}", async Task<Results<Ok<ReportJob>, NotFound>> (
    Guid id, IReportJobs jobs, HttpContext http, CancellationToken ct) =>
{
    var job = await jobs.FindAsync(id, ct);
    if (job is null) return TypedResults.NotFound();

    if (job.Status is JobStatus.Queued or JobStatus.Running)
        http.Response.Headers.RetryAfter = "5"; // Seconds until the client should poll again

    return TypedResults.Ok(job); // Includes a result link once the job succeeds
});

app.MapPost("/api/orders/batch", async (IReadOnlyList<CreateOrder> commands,
    IOrderService orders, CancellationToken ct) =>
{
    var results = new List<BatchItemResult>(commands.Count);
    foreach (var command in commands) // Independent items: one failure doesn't sink the batch
    {
        try
        {
            var order = await orders.CreateAsync(command, ct);
            results.Add(BatchItemResult.Success(command.ClientRef, order.Id));
        }
        catch (ValidationException ex)
        {
            results.Add(BatchItemResult.Failure(command.ClientRef, ex.Message));
        }
    }
    return TypedResults.Ok(new BatchResult(results));
});