Start With Whatever Both Sides Agree

If you own the only client and ship it together with the server, conventions matter much less, because you can change either side. The practices below start to pay when someone outside your team integrates, because they will retry, page and parse errors in ways you don't control.

REST is more than 25 years old and still the default for "HTTP API" — but most APIs called "REST" are really "HTTP+JSON with verbs." In 2026 the bar has moved: RFC 9457 (Problem Details, July 2023) replaced RFC 7807, and .NET ships first-class OpenAPI generation built into Microsoft.AspNetCore.OpenApi (Swashbuckle is no longer the default template) with TypedResults as the recommended way to make Minimal API endpoints self-documenting on .NET 10. The question isn't "is it RESTful?" — it's "does it have stable contracts, idempotent writes, machine-readable errors, and pagination that doesn't fall over at 10M rows?"

If partners keep hitting the same problems
  • Your POST endpoint sometimes creates two rows because a client retried
  • Your error responses are HTML in some cases and JSON in others
  • You return 200 OK with {"success": false}
  • Your pagination breaks when someone inserts a row mid-scan

Use proper status codes, RFC 9457 problem details, idempotency keys, and cursor pagination.

What REST Actually Asks of You

Five practices that matter day to day, drawn from REST's uniform interface, statelessness and caching constraints:

  • Resource-oriented URLs — nouns, not verbs. /orders/123/items not /getOrderItems?id=123.
  • Standard HTTP methods — GET (safe + idempotent), PUT/DELETE (idempotent), POST (neither), PATCH (partial).
  • Status codes that mean what they say — 200/201/204/400/401/403/404/409/422/429/500/503.
  • Stateless — every request carries auth; no server session.
  • Cacheable — ETag + Cache-Control + conditional requests.

sequenceDiagram
    participant C as Client
    participant API
    C->>API: POST /orders (Idempotency-Key)
    API-->>C: 201 Created, Location /orders/123
    C->>API: GET /orders/123 (If-None-Match: etag)
    API-->>C: 304 Not Modified

Designing a Real Resource API

Step 1: Resource-oriented routing in ASP.NET Core 10

var app = WebApplication.CreateBuilder(args).Build();

var orders = app.MapGroup("/orders").WithTags("Orders");

orders.MapGet("/",         ListOrders);             // 200 + array
orders.MapGet("/{id:long}", GetOrder);              // 200 / 404
orders.MapPost("/",         CreateOrder);           // 201 + Location
orders.MapPut("/{id:long}", ReplaceOrder);          // 200 / 204
orders.MapPatch("/{id:long}", PatchOrder);          // 200 + JSON Patch (RFC 6902)
orders.MapDelete("/{id:long}", DeleteOrder);        // 204
orders.MapGet("/{id:long}/items", ListOrderItems); // sub-resource

app.Run();
✅

Check it: Read your routes aloud. Each should be a thing, with the method saying what happens to it. Then send a request that fails validation and check the status code. It should not be 200.

Step 2: Idempotency keys for safe POST retries

// Idempotency key: client supplies a UUID; server stores the response for 24h
async Task<IResult> CreateOrder(
    HttpContext ctx, OrderRequest body, IIdempotencyStore store)
{
    var key = ctx.Request.Headers["Idempotency-Key"].FirstOrDefault();
    if (string.IsNullOrEmpty(key))
        return TypedResults.Problem(
            title: "Idempotency-Key header required",
            statusCode: 400, type: "https://errors.example.com/missing-idempotency-key");

    if (await store.TryGetAsync(key) is { } cached)
        return TypedResults.Json(cached.Body, statusCode: cached.Status);

    // Two retries can both reach this line, so claim the key atomically in real code,
    // for instance with a unique insert before doing the work
    var order = await CreateOrderInDb(body);
    await store.SaveAsync(key, 201, order, ttl: TimeSpan.FromHours(24));
    return TypedResults.Created($"/orders/{order.Id}", order);
}
// Left as Task<IResult> here because the cached-replay branch needs a dynamic
// status code — a Results<...> union shines when the branches are fixed (Step 5).
✅

Check it: Send the same create request twice with the same key. You should get the same response both times, and one row in the database.

Step 3: RFC 9457 Problem Details for errors

// AddProblemDetails has been built in since .NET 7; just enable it
builder.Services.AddProblemDetails();

// With app.UseExceptionHandler(), an unhandled exception also returns a problem
// details response (a 500) to clients that accept JSON

// Or return one explicitly — TypedResults.Problem over Results.Problem on .NET 10
return TypedResults.Problem(
    type:    "https://errors.example.com/inventory/exhausted",
    title:   "Inventory exhausted",
    detail:  "SKU widget-42 has 0 units available",
    instance: $"/orders/{id}",
    statusCode: 409,
    extensions: new Dictionary<string, object?> { ["sku"] = "widget-42" });

// Wire response:
// Content-Type: application/problem+json
// { "type": "...", "title": "...", "status": 409, "detail": "...",
//   "instance": "/orders/123", "sku": "widget-42" }
✅

Check it: Trigger three different errors on three endpoints and compare the bodies. They should share one structure, and a client should be able to tell them apart by the type field alone.

Step 4: Cursor pagination (not OFFSET)

// Keyset / cursor pagination — stable under inserts, O(log n) lookups
public record OrderPage(IReadOnlyList<Order> Items, string? NextCursor);

async Task<OrderPage> ListOrders(string? cursor, int limit = 50)
{
    limit = Math.Clamp(limit, 1, 200);
    var afterId = cursor is null ? long.MaxValue : DecodeCursor(cursor);

    var items = await db.Orders
        .Where(o => o.Id < afterId)
        .OrderByDescending(o => o.Id)
        .Take(limit + 1)
        .ToListAsync();

    // The cursor is the last row returned, not the extra row fetched to detect a next page
string? next = items.Count > limit ? EncodeCursor(items[limit - 1].Id) : null;
    return new OrderPage(items.Take(limit).ToList(), next);
}
// Response: { items: [...], nextCursor: "eyJpZCI6MTIzfQ==" }
✅

Check it: Page through a list while inserting new rows into it. Every original row should appear exactly once.

Step 5: ETags + conditional requests

// Results<...> + TypedResults (the .NET 10 idiom) instead of Task<IResult> + Results:
// the union return type feeds the OpenAPI document, so it's less likely to drift.
async Task<Results<NotFound, StatusCodeHttpResult, Ok<Order>>> GetOrder(long id, HttpContext ctx)
{
    var order = await db.Orders.FindAsync(id);
    if (order is null) return TypedResults.NotFound();

    // Use the bytes: GetHashCode on a byte[] differs per instance, so it would never match
var etag = $"\"{Convert.ToHexString(order.RowVersion)}\"";
    ctx.Response.Headers.ETag = etag;   // a 304 sends the ETag the 200 would have sent
    if (ctx.Request.Headers.IfNoneMatch == etag)
        return TypedResults.StatusCode(304);

    ctx.Response.Headers.CacheControl = "private, max-age=60";
    return TypedResults.Ok(order);
}
✅

Check it: Fetch a resource, then fetch it again with the ETag you were given. The second response should be a 304 with no body.

Step 6: Versioning at the URL or media type

// URL versioning — easiest to debug, hardest to evolve
app.MapGroup("/v1/orders")...
app.MapGroup("/v2/orders")...

// Accept-header versioning — cleaner but harder to test in a browser
// Accept: application/vnd.example.order+json; version=2
// See the API Versioning article for the full breakdown.

Partial Updates: Say What null Means

PUT replaces the whole resource, so a client that sends only the fields it changed wipes the rest. Most APIs therefore also offer PATCH, and then have to decide what a partial document means. Two standards exist, and picking one explicitly saves a long argument later:

  • JSON Merge Patch (RFC 7396), media type application/merge-patch+json. Send the fields to change; a field set to null means “remove it”; a missing field means “leave it alone”. Simple and readable, and it covers most business resources.
  • JSON Patch (RFC 6902), media type application/json-patch+json. A list of operations such asadd, remove, replace and test. More verbose, but it can change one element of an array and can assert a value before changing it.

The bug to design against is the one where a client cannot tell “clear this field” from “I did not send this field”. In C#, a plain DTO with nullable properties loses that difference during deserialisation. Model it explicitly, or read the raw JSON document and apply merge-patch rules to it.

Long-Running Operations

Some requests take longer than any client should wait on a connection: generating a report, importing a file, provisioning an account. Holding the request open for minutes fails at the first proxy timeout. Return 202 Accepted with aLocation header pointing at an operation resource, and let the client poll it:

POST /reports            -> 202 Accepted
                            Location: /operations/op_81f2
                            Retry-After: 5

GET /operations/op_81f2  -> 200 { "status": "running", "progress": 0.4 }
GET /operations/op_81f2  -> 200 { "status": "succeeded",
                                  "result": "/reports/rep_33a1" }

Put a Retry-After on the operation responses so clients do not hammer it, keep failed operations around long enough for someone to read the error, and offer a webhook for partners who would rather be told than poll.

✅

Check it: Start a long operation and drop the connection. The work should carry on, and polling the operation resource should show its progress and then its result.

Changing an API Without Breaking Callers

Adding a response field is safe for well-behaved clients. Adding a value to an enum is not: a client with a strictswitch or a generated enum type can fail on a value it has never seen. Document enums as open (“new values may be added”) from day one, and treat a new value as a change worth announcing.

For things you will remove, announce it in the responses themselves. The Deprecation header (RFC 9745) says a resource is deprecated, and the Sunset header (RFC 8594) gives the date it stops working. Log which clients still call deprecated endpoints, contact them by name, and only remove the endpoint when that log goes quiet, not when the calendar says so.

Mistakes Partners Notice First

  1. Returning 200 for errors. 200 OK + {success: false} defeats every HTTP caching and monitoring tool. Use 4xx/5xx with problem+json.
  2. Non-idempotent POST without idempotency keys. Mobile clients retry. You will get duplicate orders. AnIdempotency-Key header, currently an IETF draft, is the cheapest fix.
  3. OFFSET pagination on big tables. OFFSET 1_000_000 reads a million rows to skip them. Use cursor pagination keyed on (timestamp, id).
  4. Verbs in URLs. POST /createOrder is RPC, not REST. Pick one — both is the worst of both.
  5. No Location header on 201. Clients shouldn't have to construct the URL of the resource they just created.
  6. Different error shapes per endpoint. Pick one (RFC 9457 problem details), enforce it via middleware, document it once.

Try It on Your Own System This Week

Three checks on an API that other people call, about an hour in total:

  1. Search your responses for a 200 that carries an error. Each one hides a failure from every cache and monitor between you and the client.
  2. Retry a create request by hand. If you get two records, your partners already have duplicates.
  3. Collect the error bodies from five endpoints. Count the different shapes. The target is one.

Conventions I Would Adopt

  • Resource URLs (nouns), correct HTTP verbs, correct status codes — get these three right and you've done most of the work.
  • RFC 9457 application/problem+json is the 2026 standard for errors. .NET has had it built in since .NET 7.
  • Always require an Idempotency-Key on POST endpoints that create or charge.
  • Cursor pagination, not OFFSET. Always.
  • ETags + 304 cut bandwidth dramatically for hot reads.
  • Generate the OpenAPI doc from the code (built in since .NET 9). Prefer TypedResults over Results on .NET 10 so the doc is less likely to drift from what the endpoint actually returns.
  • Don't reinvent. RFC 9457 (problem details), RFC 9110 (HTTP semantics, including range requests), RFC 8288 (Link), RFC 6585 (429) cover most needs.

Errors a Machine Can Act On

Use RFC 9457 Problem Details for errors, with a stable type, a human title, and fields for what went wrong. Clients can branch on it, and agents can read detail and correct themselves. A plain 400 with no body wastes a retry, and it wastes a developer's afternoon.