Everything I know about good API design

Good API design requires balancing simplicity with long-term flexibility, prioritizing familiar patterns that developers can understand without extensive documentation.

The principle of "do not break userspace" is fundamental—API maintainers must avoid removing or changing field types, as breaking changes harm downstream consumers, though additive changes like new response fields are acceptable. When breaking changes are necessary, versioning allows serving multiple API versions simultaneously, enabling existing consumers to upgrade at their own pace, though versioning should be used only as a last resort due to maintenance complexity.

Ultimately, an API's success depends primarily on the underlying product value rather than elegant design; users tolerate poorly designed APIs if the service they provide is sufficiently valuable.