At Gr4vy, we are committed to providing a stable, reliable, and predictable API for our merchants. Our goal is to empower you to build robust integrations with confidence, knowing that your code won’t break unexpectedly. This guide outlines our approach to API compatibility and how we manage changes.We follow industry best practices for REST APIs to ensure a seamless experience. Our strategy is centered on two key principles: backward compatibility for our API and forward compatibility for your client integration.
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.
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.
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.
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.
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.
By following these principles, we aim to provide a powerful and stable platform that you can build on for years to come.
