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.
Retiring Older Versions
We commit to our customers to have two-year support and lifespan for a specific API version. We will work with you to help transition your code to the latest version.
Testing and Deployment Process
At Shipwell, we prioritize delivering high-quality software while maintaining a rapid pace of innovation. To achieve this, we have implemented a robust testing and deployment process designed to ensure reliability, minimize disruptions, and provide early access to new features for our customers. Below is an overview of our approach:
Agile Development and Release Cycles
Our normal development process leverages Agile software development principles, allowing for flexibility and rapid iteration. We operate on a recurring release cycle (check with the support team for the exact release cycle), enabling us to continuously deliver updates and enhancements to our platform.
Testing Process Overview
Code Review and QA Testing in Development Environment
Our testing process begins in the development environment, where code reviews and quality assurance (QA) testing is conducted to validate the functionality and stability of new code. This ensures that most issues are identified and addressed early in the development cycle. Further, as part of our development process we implement unit tests in new capabilities.
Automated and Manual Regression Testing
Once the initial QA testing is complete, we perform both automated and manual regression testing in our regression and sandbox environments as part of our release cycle. This step ensures that new changes do not negatively impact existing functionality.
Performance and Load Testing
To ensure our platform can handle real-world usage, we conduct performance and load testing in the regression environment. This load testing is performed using a multiple level of even our peak levels of our environment to ensure stability and use real-life scenarios being performed to emulate real-customer load. This helps us identify and resolve any potential bottlenecks or scalability issues before deployment.
Environment Management and Release Preparation
Regression and Sandbox Environments
A week prior to major releases, we populate our regression and sandbox environments with the latest updates. This allows our teams to thoroughly test the changes in a controlled environment that closely mirrors production.
Bug Identification and Resolution
During this testing period, any bugs identified are promptly addressed in the regression and sandbox environments. While this process is ongoing, customers may occasionally encounter temporary issues. Rest assured, these bugs are resolved prior to the production release.
Combining Early Access and Innovation
Our testing and deployment process is designed to strike a balance between providing customers with early access to new features and maintaining the reliability of our platform. By allowing customers to experience changes early in sandbox, we gather valuable feedback while continuing to support our commitment to rapid innovation.
This approach ensures that Shipwell delivers high-quality software updates while minimizing disruptions and maintaining a seamless experience for our customers. If you have any questions about our testing and deployment process, please don't hesitate to reach out to our support team.