Our Commitment: Backward Compatibility
Backward compatibility means that your existing code will continue to work as we update our API. We ensure this by strictly adhering to the following rules for any API updates:- Additive Changes Only: We will only introduce non-breaking, additive changes to our existing API. This includes:
- Adding new API endpoints.
- Adding new, optional request parameters to existing endpoints.
- Adding new properties to API response bodies.
- Adding new values to existing enum fields.
- No Breaking Changes (Without Notice): We will never remove or rename existing fields or endpoints in a backward-compatible update. Your current integration will continue to function as expected.
Your Responsibility: Forward Compatibility
Forward compatibility is the responsibility of the client, and the easiest way to achieve this is through our SDKs. Forward compatibility means that client code should be resilient to the additive changes mentioned above. Your application should be able to handle unexpected properties in API responses without crashing or throwing errors.Using Gr4vy SDKs
The easiest way to ensure forward compatibility is to use our official SDKs. They are designed to handle new response fields gracefully, allowing you to adopt new features at your own pace without being forced to update your code.Building Your Own Integration
If you are not using one of our SDKs, you must ensure that your HTTP client and JSON parser are configured to ignore unknown properties in the response body. Most standard libraries do this by default, but it is crucial to verify this behavior to prevent your integration from breaking when we enhance our API.How We Handle Breaking Changes
While we strive to avoid them, there may be rare occasions where a breaking change is necessary to improve our services, enhance security, or deprecate a feature. A breaking change is any modification that is not backward-compatible, such as removing a field or changing a data type. In these situations, we promise to provide:- Advance Notice: We will communicate any planned breaking changes at least 30 days in advance. This notice will be sent via email and Slack, and will be posted on our developer changelog.
- Clear Documentation: We will provide clear documentation and a migration guide to help you adapt your code to the new update.
- Collaborative Support: We understand that every team’s development cycle is different. If the 30-day window presents a significant challenge for your organization, we will work with you to find a viable solution. Our support team is here to help you through the transition.