api-and-interface-design

1# API and Interface Design
2 
3## Overview
4 
5Design stable, well-documented interfaces that are hard to misuse. Good interfaces make the right thing easy and the wrong thing hard. This applies to REST APIs, GraphQL schemas, module boundaries, component props, and any surface where one piece of code talks to another.
6 
7## When to Use
8 
9- Designing new API endpoints
10- Defining module boundaries or contracts between teams
11- Creating component prop interfaces
12- Establishing database schema that informs API shape
13- Changing existing public interfaces
14 
15## Core Principles
16 
17### Hyrum's Law
18 
19> With a sufficient number of users of an API, all observable behaviors of your system will be depended on by somebody, regardless of what you promise in the contract.
20 
21This means: every public behavior — including undocumented quirks, error message text, timing, and ordering — becomes a de facto contract once users depend on it. Design implications:
22 
23- **Be intentional about what you expose.** Every observable behavior is a potential commitment.
24- **Don't leak implementation details.** If users can observe it, they will depend on it.
25- **Plan for deprecation at design time.** See `deprecation-and-migration` for how to safely remove things users depend on.
26- **Tests are not enough.** Even with perfect contract tests, Hyrum's Law means "safe" changes can break real users who depend on undocumented behavior.
27 
28### The One-Version Rule
29…