Learn about API versioning and updating, as well as non-breaking and breaking changes.
Your account's API version determines the allowable requests and the response structure returned by those requests. The version also defines the structure of generated events. Your account is automatically set to the latest version when you sign up for the Digital River API.
We try to maintain backward compatibility. We do, however, version the Digital River API when a change creates compatibility issues. Each version contains breaking changes that may require you to update your workflow. All versions are dated and we allow you to remain on your current version until you're ready to update to the latest version. Once you've upgraded, you still have the ability to roll back your API version. We also provide you a number of other options for configuring and testing versions.
We will release non-breaking changes without introducing new versions. Your code will be able to handle these changes no matter what version it's on. The following changes are non-breaking, and the descriptions for these non-breaking changes appear in the latest version of the documentation:
- Adding a new API resource
- Adding a new method to an API resource
- Adding new optional request parameters to existing API methods
- Adding new properties to an existing API resource
- Changing the order of properties in existing API responses
- Changing existing error response codes or messages
- Adding a field to a request or response
- Adding a value to an enum
- Adding new event types
- Adding or removing prefixes (such as
sku_for SKU IDs)
- Changing the length or format of strings, such as object IDs, error messages, and other human-readable strings
Periodically we release new features that require you to apply changes to your application before you can safely update to the latest version without disruption. These features are "breaking changes."
The following changes are breaking:
- Adding new or modifying existing validation to an existing API resource
- Requiring a parameter that was not required before
- Modifying the expected payload of webhooks and async callbacks
- Changing the data type of an existing field
- Changing the supported filtering for existing API resources
- Renaming a field or API resource
- Adding a new feature that will change the meaning of a field
- Removing an existing field or API resource
- Changing the URL structure of an existing API resource
Image: Sample notification of a breaking change
You should always ensure that your API keys are configured for the version expected by your code. In other words, when your code is deployed from test to production, the version on the keys should match the code version.
When performing configurations, we provide you the ability to test a new version, create a restricted key and assign it to a version, create a webhook and assign it to a version, and test a version with a single API request.
We recommend that you update and test a new API version in your test environment before you update the API version in the production environment. Your production environment can remain on the production version until you are ready to upgrade to the latest version. This allows you to continue using your API keys associated with your production environment while testing a new version in your test environment. When you finish testing, you can update your production environment.
You can test a single API request without upgrading your API key. Select a version of the library to change the API version used and create a webhook endpoint with the same API version as the
DigitalRiver.API_VERSIONproperty in the library. Use the Release notes to find the API version you need and view all breaking changes.
To set an API version with a specific request, send the version number in the header: