Everything here, newest first — working notes and longer articles in one list.
16 entries · 0 articles · 16 notes
The status endpoint is a contract. Publish a small, stable state vocabulary instead of your internal states, report a failed job as a successful status call, and pick one status code convention and hold it.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
