The Stream

Notes and articles, newest first All entries →
Note 12 Nov 2026 Idempotency Matters More Now That AI Is Calling Your API AI agents decide at runtime how many times to call your API, which turns every POST into a retry risk. Make operations naturally idempotent where you can, detect and replay where you can't, and enforce it at write time. Idempotency 4 min · 4 links Note 11 Nov 2026 Canonical Serialization: Why the Same Object Hashes Differently Serialization isn't canonical, so the same object can hash differently across systems. If a payload hash drives duplicate detection, sort the token tree with an ordinal comparer and decide arrays and nulls on purpose. Idempotency 4 min · 2 links Note 10 Nov 2026 Assigning Operation IDs When Your API Returns a 202 Using the client's ID as the operation ID will eventually point one customer at another customer's job. Key uniqueness on the client plus their value, and enforce authorization on every status call. Long Running Operations 5 min · 4 links Note 09 Nov 2026 Service Bus Topics vs Queues: Which One Do You Actually Need? Most teams reach for a Service Bus topic because it sounds more flexible. Count workflows, not services: if one workflow consumes the message, a queue is the right call. Messaging 3 min · 1 link Note 08 Nov 2026 What 202 Accepted Actually Means for a Long-Running API A 202 is as easy to return as a 200. What it commits you to is validating before you accept, publishing a way to track the work, and having an answer ready when the work finishes and nobody is listening. Long Running Operations 4 min · 3 links Note 05 Nov 2026 Webhooks Are Four Problems, Not One HTTP Call Calling a customer's URL sounds trivial. It's really four problems: who may subscribe, proving the call came from you, surviving their outage, and not slowing down the request that triggered it. Webhooks 3 min · 2 links Note 03 Nov 2026 Idempotency-Key: Same Key, Same Outcome A POST that timed out leaves the caller with nothing safe to do. An Idempotency-Key header, backed by a key derived into the data and a database that rejects duplicates, makes the retry safe. Idempotency 3 min · 3 links Note 29 Oct 2026 The Gap Between Saving and Announcing Save the record, then publish the event, and a crash in between means nobody hears about it. The outbox pattern closes the gap, and the price is at-least-once delivery your handlers have to survive. Background Processing 2 min · 3 links Note 27 Oct 2026 Retries Multiply: Designing How Your API Fails Three layers that each retry 3 times turn one click into 27 database calls during an incident. Retry at one layer, fit every budget inside its caller's, and only retry writes that are safe to repeat. Resilience 2 min · 3 links Note 24 Oct 2026 Readiness Checks That Don't Turn a Slowdown Into an Outage A health check that fails on slowness is powerful and easy to overdo. If every instance reports unready at once, the load balancer has nowhere to send traffic and your probe caused the outage. Observability 2 min · 2 links Note 22 Oct 2026 Paging and Caching Decisions That Bite Later Making an API fast is easy. Making it fast without serving stale data or someone else's data means picking your paging shape before callers depend on it and never letting a cache key forget who asked. Performance 2 min · 2 links Note 20 Oct 2026 CORS Is Not Security (and Your Rate Limiter Probably Isn't Global) CORS only tells browsers what they may read, and the built-in rate limiter counts per instance. Both work in the demo and leak in production once you forget which assumption you were making. Security 3 min · 1 link Note 17 Oct 2026 403 or 404, and Other Authorization Calls to Make on Purpose A 403 tells the caller the thing exists. Which status you return on a denial, where identity comes from, and whether endpoints depend on how roles are issued are all decisions most APIs make by default. Security 3 min · 3 links Note 15 Oct 2026 What Counts as a Breaking Change in Your API Cleaning up your error handling can break callers. Know which changes are breaking, keep validation rules where they belong, and version from day one so v1 gets deprecated on a schedule instead of broken on a Tuesday. Api Design 2 min · 3 links Note 13 Oct 2026 Vertical Slices or Controllers: What You Actually Trade Controller to service to store means a one-line change touches three folders. Vertical slices fix that, at the cost of some duplication and a conventions problem you should solve early. Api Design 2 min · 1 link

Recent Notes

View all 11 →
Series in progress

Nothing running yet. A series forms when entries share a reading order.

Most connected tags All tags →
aspnet-core idempotency api-design api-keys authorization http-status-codes polling problem-details webhooks 202-accepted ai-agents api-versioning architecture async-apis at-least-once-delivery authentication azure-service-bus background-services caching circuit-breaker

After the Demo

One issue a week: a production problem, what actually fixed it, and what I'd do differently. .NET, Azure, and AI.