Shipwell considers the following changes to be backwards-compatible:
- Adding new API core and sub-resources.
- Adding new optional request parameters to existing API methods.
- Adding new properties to existing API responses.
- Changing the name or order of properties in existing API responses.
- Changing the length or format of object UUIDs or other opaque strings.
- You can safely assume object IDs we generate will never exceed 255 characters, but you should be able to handle IDs of up to that length. If for example you’re using MySQL, you should store IDs in a VARCHAR(255) COLLATE utf8_bin column (the COLLATE configuration ensures case-sensitivity in lookups).
- Adding new event types. (Your webhook listener should gracefully handle unfamiliar event types)
- Changing the actions of an endpoint
- Changes the structure of the response body
Providing extensive backwards compatibility isn’t free; every new version is more code to understand and maintain. We try to keep what we write as clean as possible, but given enough time dozens of checks on version changes that can’t be encapsulated cleanly will be littered throughout the project, making it slower, less readable, and more brittle. We take a few measures to try and avoid incurring this sort of expensive technical debt.
Even with our versioning system available, we do as much as we can to avoid using it by trying to get the design of our APIs right the first time. Outgoing changes are funneled through a lightweight API review process where they’re written up in a brief supporting document and submitted to an API Guidelines Group. This gives each proposed change broader visibility throughout Shipwell, and improves the likelihood that we’ll catch errors and inconsistencies before they’re released.
We are currently optimizing for speed, quality, and the developer experience. Consequently, we may change underlying data models to improve performance and add capabilities. Maintaining compatibility is important, but even so, we expect to eventually start retiring our older API versions. Helping users move to newer versions of the API gives them access to new features, and simplifies the foundation that we use to build new features.
We commit to our customers to have a 2-year support and lifespan for a specific API version. We will work with you to help transition your code to the newest and lastest and greatest version.
Updated about a month ago