Good APIs Age Slowly

14 hours ago

APIs that initially impress often lead to later maintenance troubles; trust in longevity over initial elegance.
The first version of an API is often overvalued because it's judged in a simple context before real-world dependencies emerge.
Key API design issues relate to boundaries: deciding what's public vs. private early to avoid unintended dependencies.
Expose as little as possible initially, as adding later is easier than removing after others rely on it.
Convenience in APIs can hide assumptions, leading to stiffness with new use cases; boring, honest APIs tend to last longer.
Avoid designing APIs around current frontend shapes to prevent coupling to temporary UI decisions.
Versioning doesn't excuse poor API design; stable APIs build trust and reduce coordination costs.
Good APIs are careful about what they expose, especially in responses, to prevent unintended reliance.

Hasty Briefsbeta