Move Fast and Break Things (Without Breaking Things)
a day ago
- The author open-sourced a Ruby gem called request_migrations for versioning REST APIs, inspired by Stripe's approach, to fix past design mistakes in Keygen's distribution API.
- A major mistake was treating a release as a single artifact instead of a bucket of artifacts, causing challenges like inability to have multiple versions of the same artifact and complex draft-to-publish flows.
- The fix involved creating a real artifact model, moving attributes from release to artifact, and changing the relationship from has-one to has-many, which required extensive code changes but maintained backward compatibility.
- The request_migrations gem works by applying small, single-purpose migrations to transform request/response data between API versions, allowing the codebase to focus on the current version.
- The author emphasizes that breaking changes can be undone without scrapping everything, providing a way to improve API design over time.