To manage the evolution of our API and introduce new features and changes effectively, we use a date-based versioning strategy. This section outlines how our versioning system works, helping you navigate through different versions of the API and understand the implications of updates.
Date-Based Versioning
Our API versions are identified using dates to mark the introduction of backward-incompatible changes. This means each version is represented by the date on which it was released. Adopting this versioning strategy allows us to make significant changes while clearly signaling these changes to our users.
Using Versions in API Requests
Including the version date in the URL path is mandatory for accessing our API. This requirement ensures you're always interacting with the expected version of the API. The version date is formatted as YYYY-MM-DD, which corresponds to the year, month, and day the version was released.
Example Request
For example, to use the API version released on October 1st, 2024, your request URL would look something like this:
https://api.superpayments.com/2024-10-01/payments
Incorporating the version date directly in the request URL allows for explicit control over which version of the API your application is using.
Breaking Changes
Our use of date-based versioning is specifically designed to communicate the introduction of backward-incompatible changes. Such changes might include alterations to existing endpoints, the structure of request or response bodies, or the removal of deprecated features.
Each new version indicates that there has been a change that is not backward compatible with previous versions. It is important for clients to review the changes associated with a new version before upgrading to avoid potential disruptions to their integration.
Legacy Versioning
For clients currently using our legacy v2 API, we have prepared upgrading documentation to facilitate your transition to the new date-based versioning system. This documentation provides detailed guidance on the differences between the v2 API and the newer versions, as well as step-by-step instructions for updating your integration. To ensure a smooth upgrade process and minimize potential disruptions to your services, we strongly recommend reviewing the upgrading documents before making any changes. You can find these resources in the "Upgrading" "Upgrading" section of our documentation.
Conclusion
By using date-based versioning, we aim to provide clarity and transparency around the introduction of significant changes to our API. This approach allows you to make informed decisions about when to upgrade your integration, based on the understanding that new versions may include backward-incompatible changes. For detailed information on migrating between versions and an overview of specific changes, please refer to our changelog or contact our support team.