- Checksum can be used to quickly determine whether a previously known data set has been changed
- Requests to unchanged data sets are returned in a fraction of the original time
- Allows for higher frequency of polling
- Checksum does not speed up API calls when changes occur at a generally faster rate than the freqency of polling (in fact, most are actually slowed down a tiny bit)
See example.sh for a simple use case, or follow the following steps:
- For any list endpoint (e.g.
/ledger/voucher), include the HTTP header
If-None-Matchset to any non-empty string.
- The response will contain a field
versionDigest. This is your checksum (Note: this is only a checksum when specifying the
- Perform the same request as in step 1, but now with the
If-None-Matchheader set to the checksum from step 2
- If the data set has changed, you will receive the response as usual, but with a new
- If there have not been any changes, you will (very quickly) receive a HTTP 304 Not Modified, indicating a checksum match.
The current checksum implementation has a few limitations:
- False negatives: The checksum may change even when the data set is unchanged, as it may be based on a larger data set than what was requested from the API.
- False positives: The checksum should always change when the data set is changed, but there are a few legitimate exceptions:
- Changes to user privileges between requests. Roles are not taken into account when calculating the checksum, even though the data set returned could have been different.
- Changes to objects not directly related to the API endpoint, fetched through
fields. For example, changes to the
fields=projectManager(*)) will not update the checksum for the
/projectendpoint. Changes to directly related fields will, however, also provide an updated checksum. E.g. changing
orderlinewill additionally update the checksum for
Checksum is based on the HTTP standard for ETag caching. This is why the header
If-None-Match is used for requesting a data set with a given checksum.
Instead of using the
ETag header to return the calculated checksum, the already existing property
versionDigest is overwritten. This is a temporary solution to lower risk for existing integrations, and will be replaced with the
ETag header in a later version.
The checksum system is not enabled by default for all list requests as it will slow down all API requests not taking advantage of the feature. The current implementation will perform the checksum calculation as an extra overhead to the request. This is also done temporarily to prevent breaking existing integrations.