REST API Best Practices for Dummies

A resource is a "thing" your API manages — a product, an order, a customer. Each one gets an address. Nouns in the URL, plural, no verbs — the verb comes from the HTTP method.

https://myshop.com/api/products      ← ALL products
https://myshop.com/api/products/5    ← product #5
https://myshop.com/api/products/5/reviews
                                     ← its reviews

// ✔ GOOD — nouns, plural, ids in the path
GET    /api/products/5
DELETE /api/products/5

// ✘ BAD — verbs in the URL, actions as paths
GET /api/getProduct?id=5
GET /api/products/delete/5   ← crawler bait!

HTTP already has verbs built in — REST just uses them with their real meaning. Five cover 99% of every API you'll ever build.

GET    /api/products/5   "Give me…"    (read only!)
POST   /api/products     "Create a new…"
PUT    /api/products/5   "REPLACE entirely"
PATCH  /api/products/5   "Change PART of"
DELETE /api/products/5   "Remove"

// Idempotent = same request twice → same end state
// GET, PUT, DELETE  → idempotent (safe to retry)
// POST              → NOT idempotent
//   (retry a POST → you might create 2 orders!)

Every response starts with a 3-digit verdict. Memory trick: 2xx = success · 4xx = YOU messed up · 5xx = the SERVER messed up. Using the right one is half of "best practices".

200 OK          Here's what you asked for
201 Created     Made it — here's where it lives
204 No Content  Done, nothing to show you

400 Bad Request   Your request makes no sense
404 Not Found     That resource doesn't exist
409 Conflict      A business rule blocks this
422 Unprocessable Validation failed

500 Internal Server Error  We crashed. Not you.

// ✘ Rookie mistake: 200 for everything,
//   with { "success": false } in the body

This is literally the text that travels over the network. Method + path, headers (metadata), then the body as JSON — curly braces for objects, "key": value pairs, square brackets for lists.

// ── REQUEST ──────────────────────────────
GET /api/products/5 HTTP/1.1
Host: myshop.com
Accept: application/json   ← "answer in JSON"

// ── RESPONSE ─────────────────────────────
HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 5,
  "name": "Mechanical Keyboard",
  "price": 89.99,
  "inStock": true
}

// Everything in this tutorial is about
// producing GOOD versions of that response.

dotnet new web gives you an empty Minimal API. Swagger UI adds a free interactive test page — every endpoint gets a "Try it out" button. Run with dotnet watch so the app restarts on every save.

dotnet new web -n ProductsApi
cd ProductsApi
dotnet add package Swashbuckle.AspNetCore
dotnet watch

// Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();
app.UseSwagger();
app.UseSwaggerUI();   // → http://localhost:PORT/swagger

app.Run();

The entity is your internal/database shape. DTOs are the public contract — and reading, creating and patching genuinely need different shapes. record declares each in one line.

// Models/Product.cs — INTERNAL
public class Product
{
    public int Id { get; set; }
    public string Name { get; set; } = "";
    public string? Description { get; set; }
    public decimal Price { get; set; }
    public int Stock { get; set; }
    public string InternalSupplierCode { get; set; } = "";
}                       // ⚠ must NEVER leak ─┘

// Dtos/ProductDtos.cs — PUBLIC contract
public record ProductDto(int Id, string Name,
    string? Description, decimal Price, int Stock);

public record CreateProductDto(string Name,
    string? Description, decimal Price, int Stock);
    // no Id — the SERVER assigns ids!

public record UpdateProductDto(string Name,
    string? Description, decimal Price, int Stock);

public record PatchProductDto(string? Name,
    string? Description, decimal? Price, int? Stock);
    // ALL optional: null = "don't change"

An extension method lets you write product.ToDto() anywhere. Notice what it doesn't copy: the internal supplier code never crosses the line.

// Dtos/ProductMappings.cs
public static class ProductMappings
{
    public static ProductDto ToDto(this Product p) =>
        new(p.Id, p.Name, p.Description,
            p.Price, p.Stock);
}

// usage anywhere:
var dto = product.ToDto();

// Larger project? Same idea, automated:
// AutoMapper / Mapster generate these for you.
// Start manual — you SEE what crosses the line.

One class owns the data; endpoints ask it, never touch storage directly. Register it once with DI — AddSingleton = "ONE instance, shared by everyone" (right for an in-memory list; real databases use AddScoped).

// Data/ProductRepository.cs
public class ProductRepository
{
    private readonly List<Product> _products =
    [
        new() { Id = 1, Name = "Mechanical Keyboard",
                Price = 89.99m, Stock = 12,
                InternalSupplierCode = "SUP-889-X" },
        new() { Id = 2, Name = "USB-C Hub",
                Price = 34.50m, Stock = 0,
                InternalSupplierCode = "SUP-102-A" },
    ];
    private int _nextId = 3;

    public List<Product> GetAll() => _products;

    public Product? Find(int id) =>
        _products.FirstOrDefault(p => p.Id == id);

    public Product Add(CreateProductDto d) { /* …Id = _nextId++… */ }
    public bool Delete(int id) { /* remove, return found? */ }
}

// Program.cs — register it ONCE:
builder.Services.AddSingleton<ProductRepository>();

It works! And it leaks internalSupplierCode to the internet, and its docs can't tell anyone what it returns. Both problems are invisible until someone gets hurt.

// ✘ DON'T keep this version
app.MapGet("/api/products/{id}",
    (int id, ProductRepository repo) =>
{
    var product = repo.Find(id);
    if (product is null)
        return Results.NotFound();
    return Results.Ok(product);   // ← ENTITY!
});

// GET /api/products/1 returns:
{
  "id": 1,
  "name": "Mechanical Keyboard",
  "price": 89.99,
  "stock": 12,
  "internalSupplierCode": "SUP-889-X"  // 🚨 LEAKED
}

Three upgrades: {id:int} rejects /products/abc before your code runs; the union type declares every outcome; ToDto() keeps the entity inside. Swagger now documents the 200 and 404 automatically.

using Microsoft.AspNetCore.Http.HttpResults;

app.MapGet("/api/products/{id:int}",
    Results<Ok<ProductDto>, NotFound>
    (int id, ProductRepository repo) =>
{
    var product = repo.Find(id);

    return product is null
        ? TypedResults.NotFound()
        : TypedResults.Ok(product.ToDto());
});

// The union type is a CONTRACT:
TypedResults.Ok(product);       // ❌ won't compile
TypedResults.BadRequest();      // ❌ not in the list
TypedResults.Ok(product.ToDto());  // ✅

The lambda's parameters are filled automatically, each from a different source, matched by name and type. This one rule explains every endpoint in this tutorial.

app.MapGet("/api/products/{id:int}",
    (int id,                  // ← route {id}
     string? fields,          // ← ?fields=... query
     ProductRepository repo,  // ← DI container
     HttpContext http)        // ← special type
    => ...);

app.MapPost("/api/products",
    (CreateProductDto input,  // ← JSON body!
     ProductRepository repo)  //   (complex type)
    => ...);

// Route values  → by name from the URL path
// Simple types  → from the query string
// Complex types → deserialized from JSON body
// Registered services → from DI
// HttpContext / LinkGenerator → framework

MapGroup factors out the shared /api/products prefix. Add the list endpoint and the API starts taking shape. (The list gets pagination in Section 6 — never ship an unbounded list!)

var products = app.MapGroup("/api/products");

products.MapGet("/", (ProductRepository repo) =>
    TypedResults.Ok(
        repo.GetAll().Select(p => p.ToDto())));

products.MapGet("/{id:int}",
    Results<Ok<ProductDto>, NotFound>
    (int id, ProductRepository repo) =>
{
    var product = repo.Find(id);
    return product is null
        ? TypedResults.NotFound()
        : TypedResults.Ok(product.ToDto());
});

// ✅ Checkpoint:
// GET /api/products     → JSON array, no leaks
// GET /api/products/1   → single product
// GET /api/products/999 → 404
// GET /api/products/abc → 404 (route constraint)

The union type says it all: this creates, or it explains why not. ValidationProblem produces the standard error format with every failed field listed.

products.MapPost("/",
    Results<Created<ProductDto>, ValidationProblem>
    (CreateProductDto input, ProductRepository repo) =>
{
    // collect ALL errors, not just the first
    var errors = new Dictionary<string, string[]>();

    if (string.IsNullOrWhiteSpace(input.Name))
        errors["name"]  = ["Name is required."];
    if (input.Price < 0)
        errors["price"] = ["Price cannot be negative."];
    if (input.Stock < 0)
        errors["stock"] = ["Stock cannot be negative."];

    if (errors.Count > 0)
        return TypedResults.ValidationProblem(errors);

    var product = repo.Add(input);

    // 201 + Location header + body
    return TypedResults.Created(
        $"/api/products/{product.Id}",
        product.ToDto());
});

In Swagger: POST → Try it out → paste the JSON → Execute. Or from any terminal with curl (-i shows the headers so you can see Location).

curl -i -X POST http://localhost:5088/api/products \
  -H "Content-Type: application/json" \
  -d '{"name":"Wireless Mouse","price":25.99,"stock":30}'

HTTP/1.1 201 Created
Location: /api/products/3
Content-Type: application/json

{"id":3,"name":"Wireless Mouse",
 "description":null,"price":25.99,"stock":30}

// Now break it on purpose — empty name, price -5:
HTTP/1.1 400 Bad Request
{
  "title": "One or more validation errors occurred.",
  "errors": {
    "name":  ["Name is required."],
    "price": ["Price cannot be negative."]
  }
}   // ← BOTH problems, one round-trip

The client sends the complete resource; you overwrite every updatable field. A missing field means "reset to default" — that's the contract. If that feels wrong for your use case, you want PATCH.

products.MapPut("/{id:int}",
    Results<NoContent, NotFound, ValidationProblem>
    (int id, UpdateProductDto input,
     ProductRepository repo) =>
{
    var errors = new Dictionary<string, string[]>();
    if (string.IsNullOrWhiteSpace(input.Name))
        errors["name"] = ["Name is required."];
    if (input.Price < 0)
        errors["price"] = ["Price cannot be negative."];
    if (errors.Count > 0)
        return TypedResults.ValidationProblem(errors);

    var product = repo.Find(id);
    if (product is null)
        return TypedResults.NotFound();

    // replace EVERY updatable field — PUT's contract
    product.Name        = input.Name;
    product.Description = input.Description;
    product.Price       = input.Price;
    product.Stock       = input.Stock;

    return TypedResults.NoContent();   // 204
});

Every property of PatchProductDto is nullable. The client sends only what changes; you apply only what arrived. Note input.Price is < 0 — "not null AND negative" in one pattern.

products.MapPatch("/{id:int}",
    Results<NoContent, NotFound, ValidationProblem>
    (int id, PatchProductDto input,
     ProductRepository repo) =>
{
    var product = repo.Find(id);
    if (product is null)
        return TypedResults.NotFound();

    var errors = new Dictionary<string, string[]>();
    if (input.Name is not null &&
        string.IsNullOrWhiteSpace(input.Name))
        errors["name"] = ["Name cannot be empty."];
    if (input.Price is < 0)
        errors["price"] = ["Price cannot be negative."];
    if (errors.Count > 0)
        return TypedResults.ValidationProblem(errors);

    // apply ONLY what the client sent
    if (input.Name is not null)
        product.Name = input.Name;
    if (input.Description is not null)
        product.Description = input.Description;
    if (input.Price is not null)
        product.Price = input.Price.Value;
    if (input.Stock is not null)
        product.Stock = input.Stock.Value;

    return TypedResults.NoContent();
});

// PATCH /api/products/1  { "price": 79.99 }
// → 204. Price changed. Nothing else touched.

Success = 204. Already gone = 404 (and that's still idempotent — the state after both calls is identical). And when a business rule blocks deletion, that's 409 Conflict, not 400.

products.MapDelete("/{id:int}",
    Results<NoContent, NotFound, Conflict<string>>
    (int id, ProductRepository repo) =>
{
    var product = repo.Find(id);
    if (product is null)
        return TypedResults.NotFound();

    // business rule: stocked products can't be deleted
    if (product.Stock > 0)
        return TypedResults.Conflict(
            $"Product {id} still has stock.");

    repo.Delete(id);
    return TypedResults.NoContent();
});

// 400 = "I can't UNDERSTAND your request"
// 409 = "I understand it fine — but it
//        CONFLICTS with current state"

Three lines of setup and every error — unhandled exceptions included — becomes clean, machine-readable JSON in the RFC 7807 format. Your ValidationProblem responses already speak it.

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

var app = builder.Build();
app.UseExceptionHandler(); // exceptions → 500 JSON
app.UseStatusCodePages();  // bare 404s  → JSON too

// Now ANY error comes back as:
{
  "type":   "https://tools.ietf.org/html/...",
  "title":  "Not Found",
  "status": 404,
  "detail": "Product 42 does not exist."
}

// ✘ Never again:
//   HTML error pages · stack traces
//   { "success": false, "err": "oops" }

A generic wrapper: the page of items plus the numbers a UI needs. <T> makes it reusable — today products, tomorrow orders.

public record PagedResult<T>(
    IReadOnlyList<T> Items,
    int Page,
    int PageSize,
    int TotalCount)
{
    public int TotalPages =>
        (int)Math.Ceiling(
            TotalCount / (double)PageSize);

    public bool HasPrevious => Page > 1;
    public bool HasNext     => Page < TotalPages;
}

// serializes to:
{
  "items": [ ... ],
  "page": 1, "pageSize": 10,
  "totalCount": 57, "totalPages": 6,
  "hasPrevious": false, "hasNext": true
}

Skip ignores the earlier pages, Take grabs one page's worth. Page 3, size 10 → skip 20, take 10. With EF Core the same two calls become SQL OFFSET/FETCH — the database does the work.

products.MapGet("/",
    Results<Ok<PagedResult<ProductDto>>,
            BadRequest<string>>
    (ProductRepository repo,
     int page = 1, int pageSize = 10) =>
{
    if (page < 1)
        return TypedResults.BadRequest(
            "page must be 1 or greater.");

    // NEVER trust client sizes
    pageSize = Math.Clamp(pageSize, 1, 100);

    var all = repo.GetAll();

    var items = all
        .Skip((page - 1) * pageSize)
        .Take(pageSize)
        .Select(p => p.ToDto())
        .ToList();

    return TypedResults.Ok(
        new PagedResult<ProductDto>(
            items, page, pageSize, all.Count));
});

// ✅ /api/products?page=1&pageSize=2

Each if adds one condition only when the client provided that parameter. Conditions stack: ?search=usb&inStock=true applies both. This composable style is the standard pattern for optional criteria.

IEnumerable<Product> query = repo.GetAll();

// filters — exact criteria
if (minPrice is not null)
    query = query.Where(p => p.Price >= minPrice);
if (maxPrice is not null)
    query = query.Where(p => p.Price <= maxPrice);
if (inStock == true)
    query = query.Where(p => p.Stock > 0);

// search — fuzzy text, case-insensitive
if (!string.IsNullOrWhiteSpace(search))
{
    var term = search.Trim();
    query = query.Where(p =>
        p.Name.Contains(term,
            StringComparison.OrdinalIgnoreCase) ||
        (p.Description is not null &&
         p.Description.Contains(term,
            StringComparison.OrdinalIgnoreCase)));
}

// count AFTER filtering, BEFORE paging
var filtered   = query.ToList();
var totalCount = filtered.Count;

A dictionary maps client keys to selector functions. Unknown key → null → the endpoint answers 400 listing the valid fields. The ThenBy(Id) tie-breaker keeps paging stable when values are equal.

static List<Product>? ApplySort(
    List<Product> products, string? sortBy)
{
    var sortMap = new Dictionary<
        string, Func<Product, object>>(
        StringComparer.OrdinalIgnoreCase)
    {
        ["name"]  = p => p.Name,
        ["price"] = p => p.Price,
        ["stock"] = p => p.Stock,
    };  // ← the ONLY sortable keys. Period.

    if (string.IsNullOrWhiteSpace(sortBy))
        return products                  // ALWAYS a
            .OrderBy(p => p.Id).ToList(); // default!

    // "price desc" → key + direction
    var parts = sortBy.Trim().Split(' ',
        StringSplitOptions.RemoveEmptyEntries);
    var key  = parts[0];
    var desc = parts.Length > 1 &&
        parts[1].Equals("desc",
            StringComparison.OrdinalIgnoreCase);

    if (!sortMap.TryGetValue(key, out var sel))
        return null;          // unknown → 400

    var ordered = desc
        ? products.OrderByDescending(sel)
        : products.OrderBy(sel);

    return ordered.ThenBy(p => p.Id).ToList();
}   //          └─ tie-breaker: stable pages

Filter → count → sort → page, then wrap in the envelope. Try the checkpoint URLs — including the deliberate typo that must return 400.

products.MapGet("/",
    Results<Ok<PagedResult<ProductDto>>,
            BadRequest<string>>
    (ProductRepository repo,
     string? search, decimal? minPrice,
     decimal? maxPrice, bool? inStock,
     string? sortBy,
     int page = 1, int pageSize = 10) =>
{
    // …validation + clamp (Section 6)…
    // …filters + search + count (card 1)…

    var sorted = ApplySort(filtered, sortBy);
    if (sorted is null)
        return TypedResults.BadRequest(
            $"'{sortBy}' is not a valid sort " +
            "field. Valid: name, price, stock.");

    var items = sorted
        .Skip((page - 1) * pageSize)
        .Take(pageSize)
        .Select(p => p.ToDto()).ToList();

    return TypedResults.Ok(new PagedResult
        <ProductDto>(items, page,
                     pageSize, totalCount));
});

// ✅ ?search=keyboard
// ✅ ?minPrice=50&sortBy=price desc
// ✅ ?inStock=true&page=1&pageSize=5
// ✅ ?sortBy=banana → 400 + valid fields

A normal class can't drop properties at runtime — but ExpandoObject is secretly a dictionary, so it holds any set of keys and serializes to exactly those. Reflection reads the DTO's properties; we copy over only the requested ones.

public static class DataShaper
{
    // null/empty fields → all props.
    // unknown field     → null (caller sends 400).
    public static ExpandoObject? Shape<T>(
        T source, string? fields)
    {
        var all = typeof(T).GetProperties(
            BindingFlags.Public |
            BindingFlags.Instance);

        PropertyInfo[] wanted;
        if (string.IsNullOrWhiteSpace(fields))
            wanted = all;
        else
        {
            var names = fields.Split(',',
                StringSplitOptions.TrimEntries |
                StringSplitOptions.RemoveEmptyEntries);
            var list = new List<PropertyInfo>();
            foreach (var n in names)
            {
                var hit = all.FirstOrDefault(p =>
                    p.Name.Equals(n, StringComparison
                        .OrdinalIgnoreCase));
                if (hit is null) return null;  // typo!
                list.Add(hit);
            }
            wanted = [.. list];
        }

        var shaped = new ExpandoObject()
            as IDictionary<string, object?>;
        foreach (var prop in wanted)
            shaped[JsonNamingPolicy.CamelCase
                .ConvertName(prop.Name)]
                = prop.GetValue(source);
        return (ExpandoObject)shaped;
    }
}
// GET /api/products/1?fields=name,price
// → { "name": "…", "price": 79.99 }

Name each endpoint with .WithName(), then ask LinkGenerator for URLs by name — so links survive route changes. Each link: where, what it means (rel), which verb.

public record LinkDto(
    string Href, string Rel, string Method);

// name every endpoint:
products.MapGet("/{id:int}", …)
        .WithName("GetProduct");
products.MapPut("/{id:int}", …)
        .WithName("UpdateProduct");
products.MapDelete("/{id:int}", …)
        .WithName("DeleteProduct");

// inside GET-by-id — inject LinkGenerator:
string Url(string name) =>
    links.GetUriByName(http, name, new { id })!;

var linkList = new List<LinkDto>
{
    new(Url("GetProduct"),    "self",   "GET"),
    new(Url("UpdateProduct"), "update", "PUT"),
};

// ⭐ THE POINT: state-driven links.
// Only offer actions currently ALLOWED:
if (product.Stock == 0)
    linkList.Add(new(
        Url("DeleteProduct"), "delete", "DELETE"));

((IDictionary<string, object?>)shaped)
    ["links"] = linkList;

The client checks: is there a delete link? Then show the delete button. The business rule lives on the server only. Change it tomorrow — zero clients need updating.

GET /api/products/2?fields=name,stock

{
  "name": "USB-C Hub",
  "stock": 0,
  "links": [
    { "href": ".../api/products/2",
      "rel": "self",   "method": "GET"    },
    { "href": ".../api/products/2",
      "rel": "update", "method": "PUT"    },
    { "href": ".../api/products/2",
      "rel": "delete", "method": "DELETE" }
  ]      // ← delete offered: stock is 0
}

GET /api/products/1?fields=name,stock
{
  "name": "Mechanical Keyboard",
  "stock": 12,
  "links": [ self, update ]   // no delete!
}

// ⚖ Honest advice: full HATEOAS shines for
// PUBLIC APIs. Internal API you own both
// sides of? next/prev pagination links get
// you 80% of the value at 20% of the work.

Bookmark this card. When in doubt, find the line and copy it.

// ── Verbs & success codes ─────────────────
GET    read           → 200
POST   create         → 201 + Location + body
PUT    replace ALL    → 204   (idempotent)
PATCH  change part    → 204
DELETE remove         → 204   (repeat → 404 ok)

// ── Error codes ───────────────────────────
400 can't understand   404 doesn't exist
409 business conflict  422/400 validation
500 we crashed         → ALL as ProblemDetails

// ── Typed results ─────────────────────────
Results<Ok<TDto>, NotFound, ValidationProblem>
TypedResults.Ok(dto) / .NotFound()
  / .Created(url, dto) / .NoContent()
  / .Conflict(msg) / .ValidationProblem(errs)

// ── Golden rules ──────────────────────────
API speaks DTO, never entity
Server assigns ids; id in URL, not body
Clamp every "how much" param (pageSize ≤ 100)
filter → count → sort → page
Sort/shape via ALLOWLIST; typos → 400 + hints
Shape DTOs, never entities
Links: only offer actions currently allowed

// ── List endpoint params ──────────────────
?search=  ?minPrice=  ?inStock=true
?sortBy=price desc    ?fields=name,price
?page=2&pageSize=10