23 days 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.