At Gr4vy, there is a commitment to providing a stable, reliable, and predictable API for merchants. The goal is to empower you to build robust integrations with confidence, knowing that your code won’t break unexpectedly. This guide outlines the approach to API compatibility and how changes are managed.Industry best practices for REST APIs are followed to ensure a seamless experience. The strategy is centered on two key principles: backward compatibility for the API and forward compatibility for your client integration.
Backward compatibility means that your existing code continues to work as the API is updated. This is ensured by strictly adhering to the following rules for any API updates:
Additive Changes Only: Only non-breaking, additive changes are introduced to the 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): Existing fields or endpoints are never removed or renamed in a backward-compatible update. Your current integration continues to function as expected.
Forward compatibility is the responsibility of the client, and the easiest way to achieve this is through the SDKs. Forward compatibility means that client code should be resilient to the additive changes mentioned in the preceding section. The app 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 the 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 not using one of the SDKs, ensure that the 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 the integration from breaking when the API is enhanced.
While there is a strive to avoid them, there may be rare occasions where a breaking change is necessary to improve 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, the following is provided:
Advance Notice: Any planned breaking changes are communicated at least 30 days in advance. This notice is sent via email and Slack, and is posted on the developer changelog.
Clear Documentation: Clear documentation and a migration guide are provided to help you adapt your code to the new update.
Collaborative Support: It is understood that every team’s development cycle is different. If the 30-day window presents a significant challenge for your organization, there is collaboration to find a viable solution. The support team is here to help you through the transition.
By following these principles, the aim is to provide a powerful and stable platform to build on for years to come.
