api design

Bilingual

The First Idempotency Key
5 days ago
- The author investigates the first instance of idempotency keys, unique identifiers that ensure duplicate API messages are ignored.
- Claude AI initially claimed Stripe introduced idempotency keys around 2011, but later retracted, noting Stripe popularized the header circa 2015.
- Earlier concepts include Amazon EC2's ClientToken and the 2005 POST Once Exactly specification using unique POST URLs.
- Transport-level standards like OASIS ebXML and WS-ReliableMessaging also aimed at exactly-once processing via message deduplication.
more...
Why Do React Hooks Rely on Call Order? — overreacted
6 days ago
- React Hooks rely on persistent call index between re-renders to give state variables stable identity.
- Alternative proposals like keyed state cause name clashes, especially when custom Hooks are used.
- Custom Hooks are central to Hooks, but some alternatives prevent extracting them or force extra wrappers.
- The diamond problem (two Hooks using the same underlying Hook) is naturally resolved by call order.
more...
Optimized for Change — overreacted
6 days ago
- Great API design focuses on being memorable, unambiguous, and encouraging readable, correct, and performant code.
- First-order design aspects like readability are important, but code and requirements evolve over time.
- Second-order design anticipates how code using the API will change, including moving, copying, renaming, unifying, unwinding, adding hacks, optimizing, throwing away, and debugging.
- Great APIs help developers not only fall into a pit of success but also stay there by being optimized for change.
The “Bug-O” Notation — overreacted
6 days ago
- The Bug-O notation measures how much an API or code structure slows debugging as a codebase grows, analogous to Big-O for algorithms.
- Imperative DOM manipulation without structure leads to O(n!) Bug-O due to combinatorial explosion of code paths, making debugging nearly impossible.
- Improving Bug-O can be achieved by resetting state before rendering, reducing complexity to O(n) where n is the number of rendering code paths.
- Libraries like React help by enforcing component boundaries and always recreating UI from scratch, reducing debugging trace to O(tree height).
more...
<antirez>
6 days ago
- The author spent days iterating on API designs for new modules and a Redis data type, emphasizing the critical role of user interfaces for programmers.
- Programmer UIs (APIs, libraries, command-line tools, etc.) are used daily and shape the perception of a system; simplicity is crucial.
- Iterating to find a simple UI is not perfectionism but an exploration of design space, guided by sensibility rather than strict rules.
- Good, simple UIs enable learning general concepts (micronutrients) rather than ad-hoc knowledge (junk food) that becomes obsolete.
more...
Designing APIs for Agents
20 days ago
- APIs designed for humans prioritize minimal usage patterns, good defaults, and approachable SDKs that require little documentation reading.
- APIs designed for agents prioritize clarity and explicitness, as agents can read extensive documentation and produce large amounts of code quickly.
- For agents, defaults are bad, as agents can fill in all fields explicitly based on documentation, reducing misunderstandings and bugs.
- Errors are not bad for agents; they provide opportunities to clarify API behavior, unlike for humans where onboarding errors should be minimized.
more...
Good APIs Age Slowly
a month ago
- APIs that initially impress often lead to later maintenance troubles; trust in longevity over initial elegance.
- The first version of an API is often overvalued because it's judged in a simple context before real-world dependencies emerge.
- Key API design issues relate to boundaries: deciding what's public vs. private early to avoid unintended dependencies.
- Expose as little as possible initially, as adding later is easier than removing after others rely on it.
more...

api design

The First Idempotency Key

Why Do React Hooks Rely on Call Order? — overreacted

Optimized for Change — overreacted

The “Bug-O” Notation — overreacted

<antirez>

Designing APIs for Agents

Good APIs Age Slowly