API design -- make the easy things easy and the hard things possible

APIs that are too simple cannot handle edge cases. APIs that handle every edge case are too complex for simple use cases. Users either outgrow the API or drown in configuration.

Layer API complexity: (1) Happy path should be 1-3 lines of code. (2) Common options as optional parameters with sensible defaults. (3) Advanced configuration via options object or builder pattern. (4) Escape hatches for power users (raw access, custom handlers). Example: fetch('url') is simple, but supports headers, method, body, signal, etc. when needed.

Most API usage is simple cases. If the simple case requires understanding the complex case, adoption suffers. If complex cases are impossible, users abandon the API.