FullStack Engineering CourseLesson 4 of 20 47 min
Building Web APIs with ASP.NET Core
The request pipeline
Every request to an ASP.NET Core app passes through a pipeline of middleware (small components that each handle one concern). Each middleware can do work before and after the next one, or stop the request early. For example, authentication runs before your endpoint, and the exception handler wraps everything so it can catch errors from any later step.
The order you register middleware is the order it runs, so the order matters. A typical API registers them like this:
var app = builder.Build();
app.UseExceptionHandler(); // 1. outermost: catches errors from everything below
app.UseHttpsRedirection(); // 2. redirect HTTP to HTTPS
app.UseCors(); // 3. browser cross-origin rules
app.UseAuthentication(); // 4. who is calling?
app.UseAuthorization(); // 5. are they allowed?
app.UseRateLimiter(); // 6. too many requests?
app.MapClaimsEndpoints(); // 7. your endpoints
app.Run();Some common mistakes come from the wrong order:
- UseAuthorization before UseAuthentication: authorization runs before the user is known, so every protected endpoint returns 401.
- UseExceptionHandler registered late: errors thrown by earlier middleware are not caught, and the client gets an empty 500.
- UseCors after authentication: the browser's preflight request (an OPTIONS request it sends before the real one) is rejected because it carries no token.
You can write your own middleware. This one gives every request a correlation ID (an ID that follows one request through all logs and services), so you can find all the log lines for a single request:
app.Use(async (context, next) =>
{
string id = context.Request.Headers["X-Correlation-ID"].FirstOrDefault()
?? Guid.NewGuid().ToString("N");
context.Response.Headers["X-Correlation-ID"] = id;
using (app.Logger.BeginScope(new Dictionary<string, object> { ["CorrelationId"] = id }))
{
await next(context); // run the rest of the pipeline; every log line inside gets the ID
}
});Minimal APIs and controllers
ASP.NET Core has two ways to write endpoints:
- Minimal APIs: map a route to a lambda or method with app.MapGet, app.MapPost and so on. They have less ceremony and are slightly faster. They are the default in new templates.
- Controllers: classes that inherit ControllerBase, with attributes such as [HttpGet]. They suit large APIs where you want filters, model binding conventions and a familiar structure.
Both run on the same pipeline and support the same features. This lesson uses minimal APIs. Route groups keep related endpoints together and let you apply settings once:
public static class ClaimsEndpoints
{
public static IEndpointRouteBuilder MapClaimsEndpoints(this IEndpointRouteBuilder app)
{
var claims = app.MapGroup("/api/v1/claims")
.RequireAuthorization() // applies to every endpoint in the group
.WithTags("Claims"); // groups them in the OpenAPI document
claims.MapGet("/{id:int}", GetClaim);
claims.MapPost("/", SubmitClaim);
claims.MapPatch("/{id:int}/status", UpdateStatus);
return app;
}
// Typed results: the return type documents every possible response.
static async Task<Results<Ok<ClaimDto>, NotFound>> GetClaim(int id, IClaimQueries queries, CancellationToken ct)
{
var claim = await queries.GetAsync(id, ct);
return claim is null ? TypedResults.NotFound() : TypedResults.Ok(ClaimDto.From(claim));
}
}Designing REST resources
REST (Representational State Transfer) is a style for HTTP APIs. The main ideas:
- URLs name resources (things), not actions: /claims/42, not /getClaim?id=42.
- HTTP methods say what to do with the resource.
- Status codes say what happened.
- Each request carries everything needed to handle it. The server keeps no session state between requests (this is called stateless).
| Method | Use it to | Safe | Idempotent |
|---|---|---|---|
| GET /claims/42 | Read a resource | Yes | Yes |
| POST /claims | Create a resource, or start an action | No | No |
| PUT /claims/42 | Replace a resource completely | No | Yes |
| PATCH /claims/42 | Change part of a resource | No | Not always |
| DELETE /claims/42 | Remove a resource | No | Yes |
Safe means the request changes nothing on the server. Idempotent means sending the same request twice has the same effect as sending it once. This matters because networks fail: a client that gets no answer will retry, and retrying an idempotent request is harmless. POST is not idempotent, so a retried POST can create two claims. The next lesson shows how idempotency keys fix that.
Use status codes precisely. Clients and monitoring tools rely on them:
| Code | Meaning | Typical use |
|---|---|---|
| 200 OK | Success, with a body | GET, or an update that returns the result |
| 201 Created | A resource was created | POST; include a Location header with its URL |
| 202 Accepted | Accepted, but processing continues later | Long jobs; return a URL where the client can check the status |
| 204 No Content | Success, nothing to return | DELETE, or an update that returns nothing |
| 304 Not Modified | The client's cached copy is still current; no body is sent | Conditional GET with If-None-Match (ETag) or If-Modified-Since |
| 400 Bad Request | The request is malformed | Invalid JSON, missing or invalid fields |
| 401 Unauthorized | The caller is not authenticated | Missing or expired token |
| 403 Forbidden | Authenticated, but not allowed | User lacks the role or permission |
| 404 Not Found | The resource does not exist | Unknown ID |
| 409 Conflict | The request conflicts with the current state | Duplicate, or approving a claim that is already rejected |
| 412 Precondition Failed | The resource changed since the client read it | Optimistic concurrency with ETags (next lesson) |
| 422 Unprocessable Content | Valid format, but breaks a business rule | Service date in the future |
| 429 Too Many Requests | Rate limit exceeded | Include a Retry-After header |
| 500 / 503 | Server error / temporarily unavailable | Unexpected exception / overload or maintenance |
304 saves bandwidth on repeated reads. The server sends an ETag header with a response (a version tag for that content, such as a hash or a row version). Next time, the client sends it back in an If-None-Match header. If the content has not changed, the server answers 304 with no body, and the client uses its cached copy:
static async Task<IResult> GetClaim(int id, HttpContext http, IClaimQueries queries, CancellationToken ct)
{
var claim = await queries.GetAsync(id, ct);
if (claim is null) return TypedResults.NotFound();
string etag = $"\"{Convert.ToBase64String(claim.RowVersion)}\""; // changes on every update
if (http.Request.Headers.IfNoneMatch == etag)
return TypedResults.StatusCode(StatusCodes.Status304NotModified); // nothing changed: no body
http.Response.Headers.ETag = etag;
return TypedResults.Ok(ClaimDto.From(claim));
}The same ETag is also used the other way round, to stop two users overwriting each other's changes (412 Precondition Failed). The next lesson covers that.
A POST that creates a claim should return 201 with the new resource's URL. A request that starts a long job should return 202 with a status URL, and do the work in the background (a queue and a BackgroundService, as in lesson 1):
static async Task<Created<ClaimDto>> SubmitClaim(SubmitClaimRequest request, IClaimService service, CancellationToken ct)
{
var claim = await service.SubmitAsync(request.ToClaim(), ct);
return TypedResults.Created($"/api/v1/claims/{claim.Id}", ClaimDto.From(claim)); // 201 + Location
}
static async Task<Accepted> StartReport(ReportRequest request, Channel<ReportJob> jobs, CancellationToken ct)
{
var job = new ReportJob(Guid.NewGuid(), request);
await jobs.Writer.WriteAsync(job, ct);
return TypedResults.Accepted($"/api/v1/reports/{job.Id}"); // 202: check this URL for progress
}Never accept or return EF Core entities directly. Use DTOs (data transfer objects: simple classes shaped for the API). Binding a request straight onto an entity lets a client set fields it should not control, such as Status or ApprovedBy. This is called overposting. DTOs also let the database schema change without breaking clients.
Errors: Problem Details (RFC 9457)
An API needs one consistent error format, so clients can handle errors the same way everywhere. RFC 9457 (Problem Details for HTTP APIs) defines a standard JSON shape, and ASP.NET Core supports it out of the box:
{
"type": "https://claims.example.com/errors/service-date-in-future",
"title": "Service date is in the future.",
"status": 422,
"detail": "Claim service date 2027-01-05 is after today.",
"instance": "/api/v1/claims",
"traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}Turn it on with AddProblemDetails, and handle exceptions in one place with an exception handler (.NET 8+). Map your own domain exceptions to the right status codes, and never send stack traces or internal messages to the client:
builder.Services.AddProblemDetails(o =>
o.CustomizeProblemDetails = ctx =>
ctx.ProblemDetails.Extensions["traceId"] = Activity.Current?.Id ?? ctx.HttpContext.TraceIdentifier);
builder.Services.AddExceptionHandler<DomainExceptionHandler>();
app.UseExceptionHandler();
app.UseStatusCodePages(); // also gives empty 404s and 405s a Problem Details body
public sealed class DomainExceptionHandler(IProblemDetailsService problems) : IExceptionHandler
{
public async ValueTask<bool> TryHandleAsync(HttpContext http, Exception exception, CancellationToken ct)
{
(int status, string title) = exception switch
{
ClaimNotFoundException => (StatusCodes.Status404NotFound, "Claim not found."),
BusinessRuleException e => (StatusCodes.Status422UnprocessableEntity, e.Message),
ConcurrencyConflictException => (StatusCodes.Status409Conflict, "The claim was changed by someone else."),
_ => (0, "")
};
if (status == 0) return false; // not ours: the default handler returns a generic 500
http.Response.StatusCode = status;
return await problems.TryWriteAsync(new ProblemDetailsContext
{
HttpContext = http,
Exception = exception,
ProblemDetails = { Status = status, Title = title }
});
}
}For input validation, return a validation problem that lists every invalid field, so the client can show all errors at once:
static async Task<Results<Created<ClaimDto>, ValidationProblem>> SubmitClaim(
SubmitClaimRequest request, IValidator<SubmitClaimRequest> validator, IClaimService service, CancellationToken ct)
{
var result = await validator.ValidateAsync(request, ct); // FluentValidation
if (!result.IsValid)
return TypedResults.ValidationProblem(result.ToDictionary()); // 400 with an "errors" object per field
var claim = await service.SubmitAsync(request.ToClaim(), ct);
return TypedResults.Created($"/api/v1/claims/{claim.Id}", ClaimDto.From(claim));
}Controllers with [ApiController] validate data annotations automatically and return this 400 for you. Minimal APIs gained built-in validation in .NET 10 (builder.Services.AddValidation()). On older versions, call a validator yourself as above.
Versioning
Once clients depend on an API, you cannot change it freely. Some changes are safe, and some break clients:
- Safe (non-breaking): adding an endpoint, adding an optional request field, adding a response field.
- Breaking: removing or renaming a field, changing a field's type or meaning, making an optional field required, changing status codes or URLs.
Make safe changes in place. For breaking changes, publish a new version and keep the old one running until clients have moved. There are four common ways for a request to say which version it wants:
| URL path | Query string | Custom header | Media type | |
|---|---|---|---|---|
| Example | /api/v2/claims/42 | /api/claims/42?api-version=2.0 | api-version: 2.0 | Accept: application/vnd.claims.v2+json |
| Visible in the URL and logs | Yes | Yes | No | No |
| Test in a browser or share a link | Easy | Easy | Needs a tool | Needs a tool |
| HTTP caching and CDNs | Works as is | Works if the cache keys on the query | Needs Vary: api-version | Needs Vary: Accept |
| Routing at a gateway | Easiest | Easy | Possible | Harder |
| Extra CORS preflight in browsers | No | No | Yes | Can be |
| One URL per resource | No | Yes | Yes | Yes |
| Default version when missing | Not possible | Easy | Easy | Easy |
- URL path: the simplest and most visible option. Gateways route it easily and caches just work. The cost is that one resource has a different URL per version, so stored links tie clients to a version. Most public APIs use it.
- Query string: the path stays the same and the version is still visible. It suits date-based versions such as api-version=2025-01-15, and Azure uses it everywhere. The cost is that clients can forget it and silently get the default version, and some caches ignore query strings.
- Custom header: clean, stable URLs. The cost is that the version is invisible in links and default logs, caches must vary on the header, and browsers send an extra preflight request for custom headers. It suits internal service-to-service APIs.
- Media type (content negotiation): the URL names the resource and the Accept header asks for a version of its format, which is the most correct in REST theory. The cost is the most complex client code, harder gateway routing and weaker tool support.
Two other approaches avoid version numbers in the usual sense:
- Date-based versions (Stripe, Azure): each breaking change ships on a date, and each client is pinned to the date it was built against. Small breaking changes need no big v2, but the server must convert responses for every past date.
- No versions at all: only ever make safe changes, and keep deprecated fields working. Clients never migrate, but the API slowly collects old fields. GraphQL APIs usually work this way.
Use major version numbers only (v1, v2), and only for breaking changes. For a public or partner API, the URL path is usually the best choice. For internal APIs, a URL path or header both work. Whatever you choose, use it the same way in every API; mixing styles across teams is worse than any single choice.
// Package: Asp.Versioning.Http
builder.Services.AddApiVersioning(o =>
{
o.DefaultApiVersion = new ApiVersion(1, 0);
o.ReportApiVersions = true; // adds api-supported-versions to responses
o.ApiVersionReader = new UrlSegmentApiVersionReader();
});
var claims = app.NewVersionedApi("Claims");
var v1 = claims.MapGroup("/api/v{version:apiVersion}/claims").HasApiVersion(1.0);
var v2 = claims.MapGroup("/api/v{version:apiVersion}/claims").HasApiVersion(2.0);
v1.MapGet("/{id:int}", GetClaimV1); // returns Amount as a number
v2.MapGet("/{id:int}", GetClaimV2); // returns Amount as { value, currency }: a breaking changeVersion only the endpoints that change, and share everything else. Plan the end of every old version:
- Report supported versions in every response (ReportApiVersions adds an api-supported-versions header).
- Mark an old version as deprecated (a Deprecation header), and announce its end date with a Sunset header (RFC 8594).
- Watch the traffic on the old version, and contact the remaining clients before you switch it off.
- Keep old versions thin: map them to the new code internally instead of keeping two full implementations.
OpenAPI and OpenAPI-first design
OpenAPI is a standard format (JSON or YAML) that describes an API: its endpoints, parameters, request and response bodies, status codes and security. Tools read it to show interactive documentation, generate client code and test the API. Since .NET 9, ASP.NET Core generates it without extra packages:
builder.Services.AddOpenApi(); // Microsoft.AspNetCore.OpenApi
app.MapOpenApi(); // serves the document at /openapi/v1.json
// For an interactive page, add a UI package such as Scalar or Swagger UI on top of this document.Typed results, route groups, WithTags, WithSummary and Produces add detail to the document automatically. This is code-first: the code is the source, and the document is generated from it.
OpenAPI-first (also called design-first or contract-first) works the other way round. You write and review the OpenAPI document before writing code:
- Write the contract: endpoints, schemas, status codes and errors, in a YAML file in the repository.
- Review it with the teams that will use the API, as you would review code.
- Lint it with a tool such as Spectral, to enforce naming and error-format rules.
- Generate code from it: client SDKs (Kiota, NSwag) and server stubs (code skeletons to fill in), so both sides share one definition.
- Test the running API against the contract in CI, so code and contract cannot drift apart.
Contract-first suits public APIs and APIs used by several teams: front-end and back-end teams can work in parallel against the agreed contract, and breaking changes show up in review instead of in production. For a small internal API, code-first is usually enough.
Pagination: offset and cursor
Never return an unbounded list. A payer with 2 million claims would time out the request and exhaust memory. There are two ways to split results into pages.
Offset pagination uses page numbers: ?page=500&size=50, which becomes OFFSET 24950 ROWS FETCH NEXT 50 in SQL. It is simple and lets users jump to any page, but it has two problems:
- It gets slower with deeper pages. The database still reads and throws away all the skipped rows, so page 500 reads 25,000 rows to return 50.
- Pages shift when data changes. If a new claim arrives while a user is paging, every row moves down by one, so the next page repeats one row; a deleted row makes them skip one.
Cursor pagination (also called keyset pagination) fixes both. Instead of a page number, the client sends a cursor: an opaque token that encodes where the last page ended. The query then starts right after that row, using an index, so every page is equally fast and stable:
public sealed record ClaimPage(IReadOnlyList<ClaimDto> Items, string? NextCursor);
static async Task<Results<Ok<ClaimPage>, BadRequest<string>>> ListClaims(
string? cursor, int? limit, ClaimsDbContext db, CancellationToken ct)
{
int size = Math.Clamp(limit ?? 50, 1, 200);
IQueryable<Claim> query = db.Claims.AsNoTracking();
if (cursor is not null)
{
if (!TryDecode(cursor, out var after)) return TypedResults.BadRequest("Invalid cursor.");
// Rows that come after the last row of the previous page, in the same sort order.
query = query.Where(c => c.SubmittedAt < after.At ||
(c.SubmittedAt == after.At && c.Id < after.Id));
}
var rows = await query.OrderByDescending(c => c.SubmittedAt).ThenByDescending(c => c.Id)
.Take(size + 1) // one extra row tells us if a next page exists
.Select(c => new ClaimDto(c.Id, c.Status, c.Amount, c.SubmittedAt))
.ToListAsync(ct);
string? next = null;
if (rows.Count > size)
{
var last = rows[size - 1];
next = Encode(last.SubmittedAt, last.Id);
rows.RemoveAt(size);
}
return TypedResults.Ok(new ClaimPage(rows, next));
}
// The cursor is opaque to clients: base64url of "ticks:id".
static string Encode(DateTimeOffset at, int id) =>
Base64Url.EncodeToString(Encoding.UTF8.GetBytes($"{at.UtcTicks}:{id}"));
static bool TryDecode(string cursor, out (DateTimeOffset At, int Id) value)
{
value = default;
try
{
var parts = Encoding.UTF8.GetString(Base64Url.DecodeFromChars(cursor)).Split(':');
value = (new DateTimeOffset(long.Parse(parts[0]), TimeSpan.Zero), int.Parse(parts[1]));
return true;
}
catch (Exception e) when (e is FormatException or IndexOutOfRangeException or OverflowException)
{
return false;
}
}Three details make it work:
- The sort must be unique. SubmittedAt alone can repeat, so Id is added as a tie-breaker. Without it, rows with the same timestamp could be skipped or repeated.
- The database needs a matching index, here (SubmittedAt DESC, Id DESC), so each page is an index seek (a jump straight to the starting row).
- The cursor is opaque. Clients must pass it back unchanged and never build it themselves, so you can change its format later.
The trade-off: with cursors, users cannot jump to page 500. That is fine for feeds, infinite scrolling, exports and API clients that read everything. Use offset pagination for small admin tables where jumping to a page number really matters.
Rate limiting
Rate limiting caps how many requests a client can make in a period. It protects the service from overload, stops one client from starving the others, and slows down abuse such as password guessing. ASP.NET Core has built-in limiters (.NET 7+):
| Limiter | How it works | Good for |
|---|---|---|
| Fixed window | N requests per fixed period (for example, 100 per minute), then the counter resets | Simple quotas; allows a burst at the window edge |
| Sliding window | Counts requests in the most recent period (for example, the last 60 seconds) instead of resetting at fixed clock times. The window is split into segments (for example, 6 segments of 10 seconds). Every 10 seconds the oldest segment drops off, and its requests stop counting. So a client never makes more than the limit in any 60 seconds, and the double burst a fixed window allows at its edge (100 at 12:00:59 plus 100 at 12:01:01) cannot happen. More segments make it smoother and more precise | Fairer per-client quotas |
| Token bucket | Tokens refill at a steady rate; each request takes one; short bursts are allowed up to the bucket size | APIs that should allow small bursts |
| Concurrency | At most N requests in progress at once | Protecting an expensive endpoint or a fragile dependency |
builder.Services.AddRateLimiter(o =>
{
o.RejectionStatusCode = StatusCodes.Status429TooManyRequests;
// One token bucket per caller: by user, or by IP address for anonymous calls.
o.AddPolicy("per-client", http => RateLimitPartition.GetTokenBucketLimiter(
partitionKey: http.User.Identity?.Name ?? http.Connection.RemoteIpAddress?.ToString() ?? "anonymous",
factory: _ => new TokenBucketRateLimiterOptions
{
TokenLimit = 100, // burst size
TokensPerPeriod = 100, // refill 100 tokens...
ReplenishmentPeriod = TimeSpan.FromMinutes(1), // ...every minute
QueueLimit = 0 // reject at once instead of queueing
}));
o.OnRejected = (context, ct) =>
{
// context.Lease is the limiter's "no" answer. Fixed window, sliding window and token bucket
// limiters attach an estimate of how long until a request would be allowed again
// (for a token bucket: until enough tokens refill). The concurrency limiter cannot know, so it adds none.
if (context.Lease.TryGetMetadata(MetadataName.RetryAfter, out TimeSpan retryAfter))
context.HttpContext.Response.Headers.RetryAfter =
((int)Math.Ceiling(retryAfter.TotalSeconds)).ToString(); // whole seconds, rounded up
return ValueTask.CompletedTask;
};
});
app.UseRateLimiter();
claims.MapPost("/", SubmitClaim).RequireRateLimiting("per-client");These limiters count in each server's memory. With five instances behind a load balancer, each one allows 100 requests, so a client can make 500. For one shared limit across instances, enforce it at the gateway (Azure API Management) or keep the counters in a shared store such as Redis. Always return 429 with a Retry-After header, so well-behaved clients know when to try again.
JSON serialisation
ASP.NET Core uses System.Text.Json. A few settings are worth setting deliberately, because changing them later breaks clients:
builder.Services.ConfigureHttpJsonOptions(o =>
{
o.SerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase; // the default for web
o.SerializerOptions.Converters.Add(new JsonStringEnumConverter()); // "Approved", not 2
o.SerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull; // omit null fields
});- Send enums as strings. Numbers break silently when someone reorders the enum.
- Send dates as ISO 8601 with an offset (DateTimeOffset), so time zones are never guessed.
- Send money as a decimal, ideally with its currency. Never use float or double for money.
- For hot paths, System.Text.Json source generation (a JsonSerializerContext) creates the serialisation code at compile time, which removes reflection and lowers allocations.
gRPC
gRPC is a framework for calls between services. It uses HTTP/2 and Protocol Buffers (Protobuf, a compact binary format) instead of JSON. You define the service in a .proto file, and tools generate strongly typed server and client code from it:
syntax = "proto3";
option csharp_namespace = "Claims.Grpc";
package claims;
service ClaimService {
rpc GetClaim (GetClaimRequest) returns (ClaimReply); // one request, one reply
rpc WatchStatus (WatchRequest) returns (stream StatusUpdate); // server streaming
}
message GetClaimRequest { int32 id = 1; }
message ClaimReply { int32 id = 1; string status = 2; int64 amount_cents = 3; }
message WatchRequest { int32 claim_id = 1; }
message StatusUpdate { string status = 1; int64 changed_at_unix = 2; }The numbers (= 1, = 2) are field tags. They identify fields on the wire, so never change or reuse them. Adding a new field with a new number is a safe change. Money is sent as whole cents (int64) because Protobuf has no decimal type.
// Server: builder.Services.AddGrpc(); app.MapGrpcService<ClaimGrpcService>();
public sealed class ClaimGrpcService(IClaimQueries queries) : ClaimService.ClaimServiceBase
{
public override async Task<ClaimReply> GetClaim(GetClaimRequest request, ServerCallContext context)
{
var claim = await queries.GetAsync(request.Id, context.CancellationToken)
?? throw new RpcException(new Status(StatusCode.NotFound, $"Claim {request.Id} not found"));
return new ClaimReply { Id = claim.Id, Status = claim.Status.ToString(),
AmountCents = (long)(claim.Amount * 100) };
}
}
// Client (in another service): registered like a typed HttpClient.
builder.Services.AddGrpcClient<ClaimService.ClaimServiceClient>(o => o.Address = new Uri("https://claims.internal"));
ClaimReply reply = await claimClient.GetClaimAsync(new GetClaimRequest { Id = 42 }, cancellationToken: ct);| REST with JSON | gRPC | |
|---|---|---|
| Format | Text (JSON), readable by people | Binary (Protobuf), smaller and faster to parse |
| Contract | Optional (OpenAPI) | Required (.proto), with generated clients |
| Streaming | Limited (Server-Sent Events, WebSockets) | Built in: server, client and two-way streaming |
| Browsers | Work everywhere | Need gRPC-Web or JSON transcoding |
| Best for | Public APIs, browsers, third parties | Calls between your own services, high volume, low latency |
A common setup is REST at the edge (for browsers and partners) and gRPC between internal services.
Webhooks
A webhook is an HTTP call your system makes to another system when something happens, such as a claim being approved. Instead of the other system polling (asking again and again whether anything changed), you push the event to a URL it registered. Webhooks cross trust boundaries and unreliable networks, so both sides need care.
When you send webhooks:
- Sign every request, so the receiver can prove it came from you. The usual method is an HMAC (a hash computed with a secret key both sides share) over a timestamp plus the body.
- Include a unique event ID, so the receiver can ignore duplicates.
- Retry failed deliveries with increasing delays (for example 1 minute, 5 minutes, 30 minutes, 2 hours), and stop after a limit.
- Send from a background queue, not from inside the business transaction. Record the event in the database in the same transaction as the change (the Outbox pattern, covered in the event-driven lesson), and let a worker deliver it.
- Keep a delivery log, so customers can see what was sent and replay failed events.
// Sending: sign "timestamp.body" with the subscriber's secret.
string json = JsonSerializer.Serialize(evt);
string timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString();
byte[] signature = HMACSHA256.HashData(subscriber.Secret, Encoding.UTF8.GetBytes($"{timestamp}.{json}"));
using var request = new HttpRequestMessage(HttpMethod.Post, subscriber.Url)
{
Content = new StringContent(json, Encoding.UTF8, "application/json")
};
request.Headers.Add("X-Event-Id", evt.Id.ToString());
request.Headers.Add("X-Timestamp", timestamp);
request.Headers.Add("X-Signature", Convert.ToHexString(signature));
var response = await http.SendAsync(request, ct); // a non-2xx answer schedules a retryWhen you receive webhooks:
- Verify the signature before trusting anything in the body. Compare signatures with CryptographicOperations.FixedTimeEquals, which takes the same time whether the first byte or the last byte differs, so an attacker cannot learn the signature by timing the comparison.
- Reject old timestamps (for example, older than 5 minutes), so a captured request cannot be replayed later.
- Answer quickly with 2xx, and do the real work in the background. Senders time out and retry slow receivers.
- Expect duplicates and events out of order. Store processed event IDs and skip repeats.
app.MapPost("/webhooks/payer", async (HttpRequest request, IOptions<WebhookOptions> options,
Channel<string> inbox, CancellationToken ct) =>
{
using var reader = new StreamReader(request.Body);
string body = await reader.ReadToEndAsync(ct);
string timestamp = request.Headers["X-Timestamp"].ToString();
string signatureHex = request.Headers["X-Signature"].ToString();
// 1. Reject old or missing timestamps (replay protection).
if (!long.TryParse(timestamp, out long sentAt) ||
Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - sentAt) > 300)
return Results.Unauthorized();
// 2. Recompute the signature and compare in constant time.
byte[] expected = HMACSHA256.HashData(options.Value.SecretBytes, Encoding.UTF8.GetBytes($"{timestamp}.{body}"));
byte[] received;
try { received = Convert.FromHexString(signatureHex); }
catch (FormatException) { return Results.Unauthorized(); }
if (!CryptographicOperations.FixedTimeEquals(expected, received))
return Results.Unauthorized();
// 3. Queue it and answer at once; a background worker processes it and skips duplicate event IDs.
await inbox.Writer.WriteAsync(body, ct);
return Results.Ok();
});API gateways
As the number of services grows, clients should not call each one directly. An API gateway is a single entry point in front of your APIs. In Azure this is usually Azure API Management (APIM). A gateway handles the shared concerns once, instead of in every service:
- Routing: one public address, forwarding each path to the right backend service.
- Security: validating JWT tokens, API keys (called subscriptions in APIM) and IP filtering.
- Rate limits and quotas across all instances, per client or per product.
- Transformation: rewriting headers, URLs or bodies, for example to keep an old contract working.
- Caching of responses that rarely change.
- Developer portal: published documentation and self-service API keys for partners.
- Monitoring: one place to see traffic, errors and latency for every API.
Keep business logic out of the gateway. It should route, protect and observe; the services should decide. A Backend-for-Frontend (BFF), a small API built for one client such as a web app, is a related pattern covered in the architecture lessons.
Check your understanding
| Question | Short answer |
|---|---|
| Why does middleware order matter? | Middleware runs in registration order. Authentication must run before authorization, and the exception handler must come first to catch errors from everything after it. |
| Which HTTP methods are idempotent? | GET, PUT and DELETE. POST is not, so a retried POST can create duplicates. |
| 201 or 202? | 201 when the resource now exists (with a Location header); 202 when the work continues in the background (with a status URL). |
| 400 or 422? | 400 when the request is malformed or fails validation; 422 when it is well formed but breaks a business rule. |
| What is Problem Details? | The RFC 9457 standard JSON error format (type, title, status, detail, instance). ASP.NET Core supports it with AddProblemDetails and IExceptionHandler. |
| Why use DTOs instead of entities? | To stop overposting, to hide internal fields, and to let the database change without breaking clients. |
| Which API changes are breaking? | Removing or renaming fields, changing types or meaning, making optional fields required, changing URLs or status codes. |
| Which versioning style should a public API use? | Usually the URL path: visible, easy to route and cache-friendly. Query strings suit date-based versions; headers suit internal APIs. |
| What is OpenAPI-first? | Writing and reviewing the OpenAPI contract before the code, then generating clients and stubs and testing the API against it. |
| Why is cursor pagination better for large data? | Each page is an index seek, so deep pages stay fast, and pages do not shift when rows are added or removed. |
| Why add Id to the cursor sort? | The sort must be unique; otherwise rows with the same timestamp can be skipped or repeated between pages. |
| Why is in-memory rate limiting not enough with many instances? | Each instance counts separately, so the real limit is multiplied. Use the gateway or a shared store such as Redis. |
| When should you choose gRPC? | For calls between your own services that need speed, a strict contract or streaming. Use REST for browsers and third parties. |
| How do you secure a webhook receiver? | Verify the HMAC signature in constant time, reject old timestamps, answer quickly and process in the background, and ignore duplicate event IDs. |
| What belongs in an API gateway? | Routing, authentication, rate limits, transformation, caching and monitoring. Not business logic. |
Summary
- Register middleware in the right order: exception handler first, then HTTPS, CORS, authentication, authorization, rate limiting and endpoints.
- Name resources with nouns, use HTTP methods and status codes precisely, and remember which methods are safe to retry.
- Return 201 with a Location header for creation and 202 with a status URL for background work; use DTOs, never entities.
- Report every error as Problem Details, from one exception handler, and list all validation errors at once.
- Make safe changes in place, and version only breaking changes, usually in the URL.
- Describe the API with OpenAPI; for shared or public APIs, design the contract first and test against it.
- Page large results with opaque cursors over a unique, indexed sort order.
- Rate limit per client, return 429 with Retry-After, and enforce shared limits at the gateway.
- Use gRPC between your own services and REST at the edge.
- Sign, retry and log outgoing webhooks; verify, de-duplicate and queue incoming ones.
- Put routing, security and quotas in the API gateway, and keep business logic in the services.
The next lesson covers the patterns that keep these APIs correct under retries and concurrent users: idempotency keys, optimistic concurrency with row versions and ETags, distributed locks and atomic Redis operations.
Comments