Everything I know about good system design
I see a lot of bad system design advice. One classic is the LinkedIn-optimized “bet you never heard of queues” style of post, presumably aimed at peop...
Everything I know about good API design
seangoedecke.comSaved December 4, 2025
Summary
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.
