4.1 Synchronization URLs
The SData synchronization protocol uses four URLs per resource kind. For example, the accounts synchronization will use the following three URLs:
http://www.example.com/sdata/myApp/myContract/-/accounts/$syncDigest http://www.example.com/sdata/myApp/myContract/-/accounts/$syncSource?trackingID=...&runName=...&runStamp=... http://www.example.com/sdata/myApp/myContract/-/accounts/$syncTarget?trackingID=...&runName=...&runStamp=... http://www.example.com/sdata/myApp/myContract/-/accounts/$syncResults?runName=...&runStamp=...
These URLs serve the following purpose:
| URL | Description |
|---|---|
| $syncDigest | The synchronization engine uses this URL to read and update the synchronization digest. This URL returns a single Atom entry that contains the digest XML payload |
| $syncSource | The synchronization engine uses this URL to read the resource changes from the source endpoint. This URL returns a synchronization feed that the engine can transfer from source to target. |
| $syncTarget | The synchronization engine uses this URL to send changes to the target endpoint. |
| $syncResults | The synchronization engine uses this URL to send the results of the target operations to the source endpoint. |
The synchronization engine should pass the following URL parameters when POSTing to these synchronization URLs:
| Parameter | Example Value | Description |
|---|---|---|
| runName | Full%20CRM%20to%ERP | A name that the engine assigned to the synchronization run. |
| runStamp | 2009-10-14T08:51:02 | The timestamp at which the synchronization run was started. |
| trackingID | DD052E5C-BFAD-4FFA-8D54-D696E4959497 | Tracking id for asynchronous requests |
The runName and runStamp parameters are primarily meant to support error handling and auditing. The engine SHOULD set these parameters at the beginning of a synchronization run and it SHOULD pass them to all POST requests during the run. The endpoints MAY use these parameter values to tag their error log and audit log entries, so that the user who reviews these logs can easily correlate the log entries with a particular run of the synchronization engine.
The runName/runStamp combination MUST uniquely identify a run of the synchronization engine. A given “run” of the engine MAY chain synchronization passes on several resource kinds across several application (usually two but could be more). On the other hand, a “run” should not span over two successive synchronization passes on the same resource kind and the same pair of applications.
A provider exposing a resource kind for synchronization MUST expose the $syncDigest URL for the resource kind and support only GET and POST operations on this URL.
A provider exposing a resource kind as target for synchronization (resources are to be created/amended/deleted within the underlying application) MUST:Expose the $syncDigest URL for the resource kind and support only GET and PUT operationsExpose the $syncTarget URL for the resource kind and support only GET, POST and DELETE operations. Support for asynchronous invocation and sequential paging MUST be provided.
A provider exposing a resource kind as source for synchronization (resources are to be cloned in external applications):MUST Expose the $syncSource URL for the resource kind and support only GET, POST and DELETE operations. Support for asynchronous invocation and sequential paging MUST be provided.MAY expose the $syncDigest URL for the resource kind and support only GET and PUT operationsMAY expose the $syncResults URLs for the resource kind(with only POST support).