Delta
General information
The Delta allows you to retrieve changes (deltas) from the Protime API since your last request. It helps reduce the volume of data by fetching only new or updated records. Note that only one delta can be active at a time in a specific collection.
Maintenance
- A delta needs regular maintenance because it expires after 72 hours. Once expired, the delta data is deleted and cannot be retrieved.
- Even if the delta endpoint returns an empty list, it will contain a deltaLink. This new deltaLink must be used to ensure it remains valid within the 72-hour expiration period.
- In the response, each object (e.g., Clocking object) includes a changeVersion field. This field is crucial for determining whether a newly received object is more recent than a previously received one. If the changeVersion of a newly received object is older than the changeVersion of a previously received object with the same unique identifier, the new object can be ignored. Note that the changeVersion field supports string comparison for determining its relative value.
Delta expiration and handling
If an expired deltalink is used it will return an error 410 Gone. This indicates that the delta is no longer available and a new delta request needs to be started.
Properties
| Property | Type | Description |
|---|---|---|
changeType |
string | The type of data change (InsertOrUpdate, Delete). |
data.changeVersion |
string | The version identifier for the change. Should be used to correctly process order of changes. |
data.... |
various types | The data of the object that was requested (e.g. clocking, person etc.) |
deltaLink |
string | A new link to obtain the new data changes in a next request. |
External references
It’s possible to use external references within the use of a delta.
Check the Collections page for the use of predefined external references or the External references page to use custom external references.
Example for clockings with an external reference(badge number):
GET https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/clockings?filter=date ge '2025-12-01'&delta&externalReferences=(people,@badge-number)
When a delta is generated, the response will include a deltaLink for fetching the next set of changes. If paging is involved, the deltaLink will always be included on the last page of the response.
Example of a new deltaLink in a GET list endpoint
{
"value": [
...
],
"deltaLink": "/connector/protimeapi/api/v1/delta/clockings?deltaToken=eyJEZWx0YUlkIjozMDA4MCwiU3RhcnRpbmdDdXJzb3IiOjQ1NTIyLCJUaW1lU3RhbXAiOiIyMDI1LTAxLTEwVDEzOjMxOjE0LjE2Njk3NjhaIn0="
}
Start a delta request
To use a delta, add the delta as a query parameter to your GET endpoint. The delta can only be used in the ‘GET list’ of a specific collection. Add delta to start a delta request.
Example:
GET https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/<resource-collection>?delta
GET delta changes
Use the deltaLink provided in the previous delta response to continue fetching changes with the Delta endpoint listed in Swagger.
Example of a delta response:
//GET https://<tenant>.myprotime.eu/connector/protimeapi/api/v1/delta/<resource-collection>?deltaToken=eyJEZWx0YUlkIjozMDA4MCwiU3RhcnRpbmdDdXJzb3IiOjQ1NTIyLCJUaW1lU3RhbXAiOiIyMDI1LTAxLTEwVDEzOjMxOjE0LjE2Njk3NjhaIn0=
{
"value": [
{
"changeType": "InsertOrUpdate",
"data": {
"changeVersion": "0000090200004BD0000A",
"id": 18618,
"calculatedTimeOfDayInMinutes": 0,
"isGenerated": false,
"person": {
"id": 7427,
"externalReferences": {
"@badge-number": "186"
}
},
"date": "2025-01-10",
"timeOfDayInMinutes": 870,
"kind": "InOut"
}
},
...
],
"deltaLink": "/connector/protimeapi/api/v1/delta/clockings?deltaToken=eyJEZWx0YUlkIjozMDA4MCwiU3RhcnRpbmdDdXJzb3IiOjQ1NTIyLCJUaW1lU3RhbXAiOiIyMDI1LTAxLTEwVDEzOjMxOjE0LjE2Njk3NjhaIn0="
}
<value>- Contains a list of all data changes for the requested collection
<ChangeType>- The type of data change. Possible values are
InsertOrUpdateorDelete
- The type of data change. Possible values are
<data>- The actual object. Has the same layout as described in the collection.
<deltaLink>- A new link to obtain the new data changes.