Api-Design
10 posts
Metering Is a Ledger, Not a Counter
Usage-based billing is a transactional problem. Reservations, compensations, and why a job that produces nothing has to refund what it held.
Trusting X-Forwarded-For Is How Rate Limiting Quietly Stops Working
If you read the leftmost X-Forwarded-For value, the client picks its own identity and a rotating header defeats your limiter entirely. Count hops instead.
Bounded Autonomy: Retry, Escalate, Never Go Silent
Every stage of an automated pipeline needs three outcomes, not two. Why automation's usual failure mode is doing nothing unnoticed, and how to design it out.
Sharing 100 Requests With Every User You Have
Strava's rate limit is per app, not per user. How that one detail shaped Pedal Wrencher: polling over webhooks, request budgets, and cooldowns.
Programmable Feeds: RSS Is the Bus
Emit began as RSS to email and grew into an ingest, transform, and deliver bus. Using RSS as the interchange format turns N times M integrations into N plus M.
Refactoring Library Interfaces
Discover techniques for improving library interfaces through thoughtful refactoring, using real-world examples while maintaining backward compatibility.
Context-Aware Library Design: Build for Your Users
Learn to design Python libraries that adapt to various user needs and experience levels, ensuring simplicity and effectiveness for all users.
Handling Deprecation: Gracefully Retiring Features
Learn to deprecate Python library features gracefully with warnings, clear communication, and migration paths that minimize disruption to your users.
Designing for Developer Joy: Python Library Ergonomics
What makes Python libraries joyful? Explore API ergonomics, from naming conventions & sensible defaults to helpful error messages that guide users to solutions.
The Art of API Design: Making the Right Things Easy
Learn principles of intuitive Python API design that make common operations simple and guide users toward best practices, while preserving advanced features.