hyrums-lawlisted

# Hyrum's Law > "With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended on by somebody." > — Hyrum Wright, 2012 ## The core idea If enough people use your API, every behavior — documented or not, intentional or not, even bugs — will be depended upon by someone. Your documented interface is not the real interface. The real interface is everything observable: response times, error message text, ordering of results, whitespace in JSON output, HTTP headers, memory usage patterns. This has a humbling implication: **as an API grows, your ability to change anything without breaking someone approaches zero.** ## Why it matters When you're building for a small set of users, you can coordinate changes. When your API is used by thousands of developers, you can't know what they've built. Some of them will have: - Parsed your error messages with regex - Depended on the alphabetical ordering of a field that you return in hash order - Built retry logic around your specific timeout behavior - Cached responses based on headers you didn't intend to be cacheable - Worked around a bug in a way that breaks when you fix the bug ## Real-world examples - Python 2→3 migration: even behavior never in the spec was depended on - Google's web infrastructure: engineers found users depending on specific memory layouts and response ordering - Any bug fix that "breaks" existing users who had worked aro