Updates to the API

Backward-compatible changes

Shipwell considers the following changes to be backward-compatible:

• Adding new API core and sub-resources.
• Adding new optional request parameters to existing API methods.
• Adding new properties to current API responses.
• Changing the name or order of properties in current 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.
• Changing the actions of an endpoint
• Changes the structure of the response body

Minimizing change

Providing extensive backward compatibility isn’t free; every new version is more code to understand and maintain. We try to keep what code we write as clean as possible. However, using older versions of the API may cause compatibility issues with your integrations.

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 funnel 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 essential, but even so, we expect to start retiring our older API versions eventually. 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.

Retiring Older Versions

We commit to our customers to have 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.