User Manual, Admin Guide, HA Cluster, Release Notes

1. Introduction

This document is a guide which will walk you through SnowMirror REST API. The purpose of the REST API is to allow developers to integrate SnowMirror with other applications.

1.1. URIs of REST API Resources

The API consists of resources identified by URIs. To call the API you have to make HTTP requests on the provided URIs. The URIs have following structure:

http://{hostname}:{port}/api/{api-version}/{resource-name}

  • hostname - name of the server where SnowMirror is running

  • port - port on which SnowMirror is running

  • api-version - version of API to use. Currently "v1" is the only option available. In future releases a version may increase

  • resource-name - name of the resource you need to operate on. The resources are described in the following chapter

Let’s say you need to get information about a synchronization. Then you will have to make GET HTTP request on a resource called http://yourSnowMirrorServer:9191/api/v1/synchronization

Also note that resources are secured. Please see Authentication and Security chapter for details.

2. Resources

2.1. /synchronization

2.1.1. GET

Returns a list of all synchronizations.

Available Responses:

  • 200 - A list of synchronizations was successfully retrieved.

    Sample Response Body (Content-Type: application/json):

    {
    "syncs": [
        {
            "id": 24,
            "name": "Account",
            "table": "Account",
            "mirrorTable": "Account",
            "columns": [
                {
                    "name": "Id"
                },
                {
                    "name": "AccountNumber"
                }
            ],
            "autoSchemaUpdate": false,
            "userQuery": null,
            "deleteStrategy": "AUDIT",
            "active": true,
            "scheduler": {
                "type": "MANUALLY",
                "beginDate": "2014-08-07"
            },
            "fullLoadScheduler": {
            	"executionType": "CLEAN_AND_SYNCHRONIZE",
                "type": "MANUALLY",
                "beginDate": "2014-08-07"
            },
            "schedulerPriority": "NORMAL"
        },
		{
			"id": 2,
			"name": "u_rest_test_table_backup-ecf7afd3902e46aabc6b4266ae20f694",
			"backup": "u_rest_test_table",
			"mirrorTable": null,
			"columns": [
				{
         			"name": "Id"
      			}
			],
			"userQuery": null,
			"deleteStrategy": "NONE",
			"active": true,
			"scheduler": {
				"type": "MANUALLY",
				"beginDate": "2014-08-07",
				"time": "04:00",
				"visible": false
			},
			"fullLoadScheduler": null,
			"schedulerPriority": "NORMAL",
			"synchronizationType": null,
			"masterTable": null,
			"attachmentDirectory": null,
			"retentionPeriod": 30,
			"format": "CSV",
			"updateBeforeSynchronizationRun": false
	   }
    ]
}

2.1.2. POST

Creates a new synchronization. Returns newly created synchronization including its ID.

Table 1. Request Body Attributes
Attribute Description

name

Display name of the synchronization.

table

Name of the table in Salesforce. One (and only one) of "table", "attachment", "backup" or "backupAttachment" attributes has to be filled in.

attachment

Name of the table in Salesforce which attachments will be synchronized. One (and only one) of "table", "attachment", "backup" or "backupAttachment" attributes has to be filled in.

backup

Name of the table in Salesforce to backup to a file. One (and only one) of "table", "attachment", "backup" or "backupAttachment" attributes has to be filled in.

backupAttachment

Name of the table in Salesforce which attachments you want to backup. One (and only one) of "table", "attachment", "backup" or "backupAttachment" attributes has to be filled in.

mirrorTable

Name of the table in mirror database where the data will be migrated.

columns

A list of columns to synchronize. If some of the columns does not exist in Salesforce then it is ignored in SnowMirror. This attribute is mandatory for tables. It must not be used for attachments.
Each column consists of:
prefix - prefix of the column
name - name of the column to synchronize

updateBeforeSynchronizationRun

Deprecated - use "autoSchemaUpdate" instead. The same as "autoSchemaUpdate".

autoSchemaUpdate

Indicates that the synchronization can update its columns meta-data (i.e. add and remove columns) before synchronization run. This way if the table changes in Salesforce the changes are automatically reflected in SnowMirror.
Allowed values: true, false

userQuery

User query is used for filtering data in Salesforce. This syntax is the same as WHERE clause in SOQL (See official SOQL Reference Guide) Only data matching the user query will be downloaded.

deleteStrategy

Specifies how the data will be deleted from mirror database based on deletes in Salesforce. For details about the strategies see Delete Strategy section in User Manual.
Allowed values: AUDIT, TRUNCATE, DIFF or NONE

active

true - synchronization is active and can be scheduled to synchronize data from Salesforce
false - synchronization is deactivated and cannot be scheduled to synchronize data from Salesforce
Allowed values: true, false

runImmediately

Determines whether initial synchronization should be done
Allowed values: true, false (default)

scheduler

Specifies when the incremental load synchronization will run. For details about the schedulers see Scheduler section in User Manual.
Allowed scheduler types: MANUALLY, DAILY, WEEKLY, PERIODICALLY, CRON

fullLoadScheduler

Specifies when the full load synchronization will run. For details about the schedulers see Scheduler section in User Manual.
Allowed scheduler types: MANUALLY, DAILY, WEEKLY, PERIODICALLY, CRON.

fullLoadScheduler.executionType

Name of an action to perform during synchronization. Allowed values: CLEAN_AND_SYNCHRONIZE, DIFFERENTIAL.

schedulerPriority

Execution priority of the job. Allowed values: HIGHEST, HIGH, NORMAL, LOW, LOWEST

retentionPeriod

How many days to keep backups

format

How to store backups. "CSV" - comma separated file. "XML" - XML files. Allowed values: CSV, XML

Request Body Format:

  • Full Request for Table Synchronization

    Sample Request Body (Content-Type: application/json):

    {
    "sync": {
        "name": "Account",
        "table": "Account",
        "mirrorTable": "Account",
        "columns": [
            {
                "name": "Id",
            },
            {
                "name": "AccountNumber",
            }
        ],
        "autoSchemaUpdate": false,
        "userQuery": "",
        "deleteStrategy": "AUDIT",
        "active": true,
        "runImmediately": true,
        "scheduler": {
            "type": "MANUALLY",
            "beginDate": "2014-08-07"
        },
        "fullLoadScheduler": {
        	"executionType": "CLEAN_AND_SYNCHRONIZE",
            "type": "MANUALLY",
            "beginDate": "2014-08-07"
        },
        "schedulerPriority": "NORMAL"
    }
}

  • Full Request for Attachment Synchronization

    Sample Request Body (Content-Type: application/json):

    {
    "sync": {
        "name": "Account_attachment",
        "attachment": "Account",
        "mirrorTable": "Account_attachment",
        "userQuery": "",
        "deleteStrategy": "DIFF",
        "active": true,
        "runImmediately": true,
        "scheduler": {
            "type": "MANUALLY",
            "beginDate": "2014-08-07"
        },
        "fullLoadScheduler": {
        	"executionType": "CLEAN_AND_SYNCHRONIZE",
            "type": "MANUALLY",
            "beginDate": "2014-08-07"
        },
        "schedulerPriority": "NORMAL"
    }
}

  • Full Request for Backup Synchronization

    Sample Request Body (Content-Type: application/json):

    {
    "sync": {
        "name": "Account",
        "backup": "Account",
        "columns": [
            {
                "name": "Id"
            },
            {
                "name": "active"
            }
        ],
        "allowInheritedColumns": true,
        "autoSchemaUpdate": false,
        "userQuery": "",
        "deleteStrategy": "NONE",
        "active": true,
        "runImmediately": true,
		"retentionPeriod": 30,
		"format": "CSV",
        "scheduler": {
            "type": "MANUALLY",
            "beginDate": "2014-08-07"
        },
        "fullLoadScheduler": {
        	"executionType": "CLEAN_AND_SYNCHRONIZE",
            "type": "MANUALLY",
            "beginDate": "2014-08-07"
        },
        "schedulerPriority": "NORMAL"
    }
}

  • Full Request for Backup Attachment Synchronization

    Sample Request Body (Content-Type: application/json):

    {
    "sync": {
        "name": "Account",
        "backupAttachment": "Account",
        "userQuery": "",
        "deleteStrategy": "NONE",
        "active": true,
        "runImmediately": true,
        "retentionPeriod": 30,
        "scheduler": {
            "type": "MANUALLY",
            "beginDate": "2014-08-07",
            "incLoadExecutionType": "INCREMENTAL_BACKUP"
        },
        "fullLoadScheduler": {
        	"executionType": "CLEAN_AND_SYNCHRONIZE",
            "type": "MANUALLY",
            "beginDate": "2014-08-07"
        },
        "schedulerPriority": "NORMAL"
    }
}

  • Manual Scheduler

    Sample Request Body With Manual Scheduler:

    {
    "sync": {
        ...

        "scheduler": {
            "type": "MANUALLY",
            "beginDate": "2014-08-07"
        }

        ...
    }
}

  • Daily Scheduler

    Sample Request Body With Daily Scheduler:

    {
    "sync": {
        ...

        "scheduler": {
            "type": "DAILY",
            "beginDate": "2014-08-08",
            "time": "22:00"
        }

        ...
    }
}

  • Weekly Scheduler

    Sample Request Body With Weekly Scheduler:

    {
    "sync": {
        ...

        "scheduler": {
            "type": "WEEKLY",
            "beginDate": "2014-08-08",
            "time": "22:00",
            "days": [ "MONDAY", "FRIDAY" ]
        }

        ...
    }
}

  • Periodical Scheduler

    Sample Request Body With Periodical Scheduler:

    {
    "sync": {
        ...

        "scheduler": {
            "type": "PERIODICALLY",
            "beginDate": "2014-08-08",
            "time": "22:00",
            "interval": "120"
        }

        ...
    }
}

  • Cron Scheduler

    Sample Request Body With Cron Scheduler:

    {
    "sync": {
        ...

        "scheduler": {
            "type": "CRON",
            "beginDate": "2014-08-08",
            "cronExpression": "0 0 12 * * ?"
        }

        ...
    }
}

Available Responses:

  • 200 - Synchronization was successfully created.

    Sample Response Body (Content-Type: application/json):

    {
    "sync": {
        "id": 1,
        "name": "Account",
        "table": "Account",
        "mirrorTable": "Account",
        "columns": [
            {
                "name": "AccountNumber"
            },
            {
                "name": "Id"
            }
        ],
        "autoSchemaUpdate": false,
        "userQuery": null,
        "deleteStrategy": "AUDIT",
        "active": true,
        "scheduler": {
            "type": "MANUALLY",
            "beginDate": "2014-08-07"
        },
        "fullLoadScheduler": {
        	"executionType": "CLEAN_AND_SYNCHRONIZE",
            "type": "MANUALLY",
            "beginDate": "2014-08-07"
        },
        "schedulerPriority": "NORMAL"
    }
}

  • 400 - Could not parse a request or validations failed.

2.1.3. DELETE

Deletes synchronizations. To be able to delete a synchronization it must not be running.

Request Format:

  • Full Request

    Sample Request body (Content-Type: application/json):

    {
    "ids": [ 1, 42 ]
}

Available Responses:

  • 200 - Synchronizations has been successfully deleted.

  • 400 - Could not parse a request.

  • 404 - No synchronization was deleted because at least one of the synchronizations could not be found.

2.2. /synchronization/action

2.2.1. GET

Returns a list of all actions which can be performed on synchronizations.

Available Responses:

  • 200 - A list of actions was successfully retrieved.

    Sample Response Body (Content-Type: application/json):

    {
    "actions": [
        "SYNCHRONIZE",
        "CLEAN_AND_SYNCHRONIZE"
        "STOP"
    ]
}

2.2.2. POST

Performs an action on the selected synchronizations.
API ignores synchronizations which are already running. It also ignores synchronizations which are deactivated.
Available actions are "SYNCHRONIZE", "CLEAN_AND_SYNCHRONIZE", "DIFFERENTIAL_SYNCHRONIZATION", "STOP"

Request Body Format:

  • Full Request

    Sample Request Body (Content-Type: application/json):

    {
  "action": "SYNCHRONIZE",
  "ids": [ 1, 2, 3 ]
}

Available Responses:

  • 200 - An action has been successfully performed. Note that some synchronizations may be ignored.

    • SYNCHRONIZE sample response

      Sample Response Body (Content-Type: application/json):

      {
    "alreadyRunningSyncIds": [ 1 ],
    "disabledSyncIds": [ 2 ]
}

    • CLEAN_AND_SYNCHRONIZE sample response

      Sample Response Body (Content-Type: application/json):

      {
    "alreadyRunningSyncIds": [ 1 ],
    "disabledSyncIds": [ 2 ]
}

    • STOP sample response

      Sample Response Body (Content-Type: application/json):

      {
    "notRunningSyncIds": [ 1 ],
    "disabledSyncIds": [ 2 ]
}

  • 404 - No action has been performed because at least one of the synchronizations could not be found.

2.3. /synchronization/{id}

2.3.1. GET

Returns detailed information about the synchronization.

Table 2. Response Body Attributes
Attribute Description

sync.id

Id of the synchronization.

sync.name

Display name of the synchronization.

sync.table

Name of the table in Salesforce. One (and only one) of "table", "attachment", "backup" or "backupAttachment" attributes has to be filled in.

sync.attachment

Name of the table in Salesforce which attachments will be synchronized. One (and only one) of "table", "attachment", "backup" or "backupAttachment" attributes has to be filled in.

sync.backup

Name of the table in Salesforce to backup to a file. One (and only one) of "table", "attachment", "backup" or "backupAttachment" attributes has to be filled in.

sync.backupAttachment

Name of the table in Salesforce which attachments you want to backup. One (and only one) of "table", "attachment", "backup" or "backupAttachment" attributes has to be filled in.

sync.mirrorTable

Name of the table in mirror database where the data will be migrated.

sync.columns

A list of columns to synchronize. If some of the columns does not exist in Salesforce then it is ignored in SnowMirror.
Each column consists of:
prefix - prefix of the column
name - name of the column to synchronize

sync.updateBeforeSynchronizationRun

Deprecated - use "sync.autoSchemaUpdate" instead. The same as "sync.autoSchemaUpdate".

sync.autoSchemaUpdate

Indicates that the synchronization can update its columns meta-data (i.e. add and remove columns) before synchronization run. This way if the table changes in Salesforce the changes are automatically reflected in SnowMirror.
Allowed values: true, false

sync.userQuery

User query is used for filtering data in Salesforce. This syntax is the same as WHERE clause in SOQL (See official SOQL Reference Guide) Only data matching the user query will be downloaded.

sync.deleteStrategy

Specifies how the data will be deleted from mirror database based on deletes in Salesforce. For details about the strategies see Delete Strategy section in User Manual.
Allowed values: AUDIT, TRUNCATE, DIFF or NONE

sync.active

true - synchronization is active and can be scheduled to synchronize data from Salesforce
false - synchronization is deactivated and cannot be scheduled to synchronize data from Salesforce
Allowed values: true, false

sync.scheduler

Specifies when the incremental load synchronization will run. For details about the schedulers see Scheduler section in User Manual.
Allowed scheduler types: MANUALLY, DAILY, WEEKLY, PERIODICALLY, CRON

sync.fullLoadScheduler

Specifies when the full load synchronization will run. For details about the schedulers see Scheduler section in User Manual.
Allowed scheduler types: MANUALLY, DAILY, WEEKLY, PERIODICALLY, CRON

sync.fullLoadScheduler.executionType

Name of an action to perform during synchronization. Allowed values: CLEAN_AND_SYNCHRONIZE, DIFFERENTIAL.

sync.schedulerPriority

Execution priority of the job. Allowed values: HIGHEST, HIGH, NORMAL, LOW, LOWEST

sync.retentionPeriod

How many days to keep backups

sync.format

How to store backups. "CSV" - comma separated file. "XML" - XML files. Allowed values: CSV, XML

status.status

Allowed values: RUNNING, SUCCESSFUL, FAILED, CANCELING, CLEANING, NEW_SYNCHRONIZATION

status.startedOn

Date and time when the last synchronization run started

status.startedBy

Username of who started the synchronization

status.latestHistoryId

Id of the record in history of synchronization

status.durationInMillis

How long it took to finish the synchronization in milliseconds

status.duration

How long it took to finish the synchronization in human-readable format

status.toInsert

How many records was SnowMirror supposed to insert (create)

status.toUpdate

How many records was SnowMirror supposed to update

status.toDelete

How many records was SnowMirror supposed to delete

status.inserted

How many records SnowMirror actually created

status.updated

How many records SnowMirror actually updated

status.deleted

How many records SnowMirror actually deleted

status.total

Sum of how many records SnowMirror actually processed

Available Responses:

  • 200 - Synchronization was successfully retrieved.

    Sample Response Body (Content-Type: application/json):

    {
    "sync": {
        "id": 1,
        "name": "Account",
        "table": "Account",
        "mirrorTable": "Account",
        "columns": [
            {
                "name": "AccountNumber"
            },
            {
                "name": "Id"
            }
        ],
        "autoSchemaUpdate": false,
        "userQuery": null,
        "deleteStrategy": "AUDIT",
        "active": true,
        "scheduler": {
            "type": "MANUALLY",
            "beginDate": "2014-08-07"
        },
        "fullLoadScheduler": {
        	"executionType": "CLEAN_AND_SYNCHRONIZE",
            "type": "MANUALLY",
            "beginDate": "2014-08-07"
        },
        "schedulerPriority": "NORMAL"
    },
    "status": {
        "status": "SUCCESSFUL",
        "startedOn": "2014-08-19 13:07",
        "startedBy": "snowmirror_api",
        "latestHistoryId": 819,
        "durationInMillis": 4000,
        "duration": "4s",
        "toInsert": 75,
        "toUpdate": null,
        "toDelete": null,
        "inserted": 75,
        "updated": 0,
        "deleted": 0,
        "total": 75
    }
}

  • 404 - Could not find the synchronization.

2.3.2. PUT

Updates a synchronization. The request body contains all fields (even those not being modified).

Table 3. Request Body Attributes
Attribute Description

id

Id of the synchronization.

name

Display name of the synchronization.

table

Name of the table in Salesforce. One (and only one) of "table", "attachment", "backup" or "backupAttachment" attributes has to be filled in.

attachment

Name of the table in Salesforce which attachments will be synchronized. One (and only one) of "table", "attachment", "backup" or "backupAttachment" attributes has to be filled in.

backup

Name of the table in Salesforce to backup to a file. One (and only one) of "table", "attachment", "backup" or "backupAttachment" attributes has to be filled in.

backupAttachment

Name of the table in Salesforce which attachments you want to backup. One (and only one) of "table", "attachment", "backup" or "backupAttachment" attributes has to be filled in.

mirrorTable

Name of the table in mirror database where the data will be migrated.

columns

A list of columns to synchronize. If some of the columns does not exist in Salesforce then it is ignored in SnowMirror. This attribute is mandatory for tables. It must not be used for attachments.
Each column consists of:
prefix - prefix of the column
name - name of the column to synchronize

updateBeforeSynchronizationRun

Deprecated - use "autoSchemaUpdate" instead. The same as "autoSchemaUpdate".

autoSchemaUpdate

Indicates that the synchronization can update its columns meta-data (i.e. add and remove columns) before synchronization run. This way if the table changes in Salesforce the changes are automatically reflected in SnowMirror.
Allowed values: true, false

userQuery

User query is used for filtering data in Salesforce. This syntax is the same as WHERE clause in SOQL (See official SOQL Reference Guide) Only data matching the user query will be downloaded.

deleteStrategy

Specifies how the data will be deleted from mirror database based on deletes in Salesforce. For details about the strategies see Delete Strategy section in User Manual.
Allowed values: AUDIT, TRUNCATE, DIFF or NONE

active

true - synchronization is active and can be scheduled to synchronize data from Salesforce
false - synchronization is deactivated and cannot be scheduled to synchronize data from Salesforce
Allowed values: true, false

scheduler

Specifies when the incremental load synchronization will run. For details about the schedulers see Scheduler section in User Manual.
Allowed scheduler types: MANUALLY, DAILY, WEEKLY, PERIODICALLY, CRON

fullLoadScheduler

Specifies when the full load synchronization will run. For details about the schedulers see Scheduler section in User Manual.
Allowed scheduler types: MANUALLY, DAILY, WEEKLY, PERIODICALLY, CRON

fullLoadScheduler.executionType

Name of an action to perform during synchronization. Allowed values: CLEAN_AND_SYNCHRONIZE, DIFFERENTIAL.

schedulerPriority

Execution priority of the job. Allowed values: HIGHEST, HIGH, NORMAL, LOW, LOWEST

retentionPeriod

How many days to keep backups

format

How to store backups. "CSV" - comma separated file. "XML" - XML files. Allowed values: CSV, XML

  • Full Request

    Sample Request Body (Content-Type: application/json):

    {
    "sync": {
        "id": 1,
        "name": "Account",
        "table": "Account",
        "mirrorTable": "Account",
        "columns": [
            {
                "name": "AccountNumber"
            },
            {
                "name": "Id"
            }
        ],
        "autoSchemaUpdate": false,
        "userQuery": null,
        "deleteStrategy": "TRUNCATE",
        "active": true,
        "scheduler": {
            "type": "PERIODICALLY",
            "beginDate": "2014-08-05",
            "time": "18:05",
            "days": [
                "WEDNESDAY"
            ],
            "interval": 1000
        },
        "fullLoadScheduler": {
        	"executionType": "CLEAN_AND_SYNCHRONIZE",
            "type": "PERIODICALLY",
            "beginDate": "2014-08-05",
            "time": "18:05",
            "days": [
                "WEDNESDAY"
            ],
            "interval": 1000
        },
        "schedulerPriority": "NORMAL"
    }
}

Available Responses:

  • 200 - The synchronization has been successfully updated.

    Sample Response Body (Content-Type: application/json):

    {
    "sync": {
        "id": 1,
        "name": "Account",
        "table": "Account",
        "mirrorTable": "Account",
        "columns": [
            {
                "name": "AccountNumber"
            },
            {
                "name": "Id"
            }
        ],
        "autoSchemaUpdate": false,
        "userQuery": null,
        "deleteStrategy": "TRUNCATE",
        "active": true,
        "scheduler": {
            "type": "PERIODICALLY",
            "beginDate": "2014-08-07",
            "time": "16:05",
            "days": [
                "WEDNESDAY"
            ],
            "interval": 1000
        },
        "fullLoadScheduler": {
        	"executionType": "CLEAN_AND_SYNCHRONIZE",
            "type": "PERIODICALLY",
            "beginDate": "2014-08-07",
            "time": "16:05",
            "days": [
                "WEDNESDAY"
            ],
            "interval": 1000
        },
        "schedulerPriority": "NORMAL"
    },
    "syncTableCleared": false
}

  • 400 - Could not parse a request or validations failed.

  • 404 - Could not find the synchronization.

2.3.3. DELETE

Deletes a synchronization. To be able to delete a synchronization it must not be running.

  • 200 - Synchronization has been successfully deleted.

  • 400 - Could not delete the synchronization.

  • 404 - Could not find the synchronization.

2.4. /synchronization/{id}/action

2.4.1. GET

Returns a list of all actions which can be performed on the synchronization.

Available Responses:

  • 200 - A list of actions was successfully retrieved.

    Sample Response Body (Content-Type: application/json):

    {
    "actions": [
        "SYNCHRONIZE",
        "CLEAN_AND_SYNCHRONIZE",
        "DIFFERENTIAL_SYNCHRONIZATION",
        "STOP_SYNCHRONIZATION"
    ]
}

  • 404 - Could not find the synchronization.

2.4.2. POST

Performs an action on the given synchronization. It is expected that the synchronization is active.
Available actions are "SYNCHRONIZE", "CLEAN_AND_SYNCHRONIZE", "DIFFERENTIAL_SYNCHRONIZATION", "STOP_SYNCHRONIZATION".

  • Full Request

    Sample Request Body (Content-Type: application/json):

    {
    "action": "SYNCHRONIZE"
}

Available Responses:

  • 200 - An action has been successfully performed.

  • 400 - Could not parse a request or could not perform an action.

  • 404 - Could not find the synchronization.

2.5. /synchronization/{id}/history

2.5.1. GET

Returns a whole history of the synchronization.

Available Responses:

  • 200 - History was successfully retrieved.

    Sample Response Body (Content-Type: application/json):

    {
    "history": [
        {
            "id": 297,
            "result": "SUCCESSFUL",
            "start": "2014-08-07 10:20",
            "end": "2014-08-07 10:23",
            "startedBy": "snowmirror_api",
            "toInsert": 0,
            "toUpdate": 891,
            "toDelete": 0,
            "inserted": 0,
            "updated": 891,
            "deleted": 0,
            "total": 891
        },
        {
            "id": 294,
            "result": "SUCCESSFUL",
            "start": "2014-08-07 00:00",
            "end": "2014-08-07 00:00",
            "startedBy": "<SCHEDULER>",
            "toInsert": 2,
            "toUpdate": null,
            "toDelete": null,
            "inserted": 2,
            "updated": 0,
            "deleted": 0,
            "total": 2
        }
    ]
}

2.6. /synchronization/{id}/history/{id}

2.6.1. GET

Returns information about the result of the specific synchronization run.

Available Responses:

  • 200 - History was successfully retrieved.

    Sample Response Body (Content-Type: application/json):

    {
    "history": {
        "id": 297,
        "result": "SUCCESSFUL",
        "start": "2014-08-07 10:20",
        "end": "2014-08-07 10:23",
        "startedBy": "snowmirror_api",
        "toInsert": 0,
        "toUpdate": 891,
        "toDelete": 0,
        "inserted": 0,
        "updated": 891,
        "deleted": 0,
        "total": 891
    }
}

  • 404 - Could not find the synchronization or could not find the history.

2.7. /synchronization/{id}/history/{id}/log

2.7.1. GET

Returns a log of the given synchronization run.

Available Responses:

  • 200 - Log file was successfully retrieved.

    Sample Response Body (Content-Type: text/plain):

    INFO: 2014-08-06 22:17:57 - Synchronization has been started
INFO: 2014-08-06 22:17:57 - No encoded query set
INFO: 2014-08-06 22:17:57 - Loading meta-data of table sys_dictionary from Salesforce
INFO: 2014-08-06 22:17:59 - sys_dictionary table meta-data loaded, creating excluded columns list
INFO: 2014-08-06 22:17:59 - No excluded columns set
INFO: 2014-08-06 22:17:59 - Synchronizing to target table sys_dictionary
INFO: 2014-08-06 22:17:59 - Getting count of records to insert, update and delete
INFO: 2014-08-06 22:17:59 - Checking existing columns in the table sys_dictionary
INFO: 2014-08-06 22:17:59 - Inserting records into table sys_dictionary
INFO: 2014-08-06 22:17:59 - Inserting all records into table sys_dictionary
INFO: 2014-08-06 22:17:59 - Getting next up to 2 keys of records which will be migrated
INFO: 2014-08-06 22:17:59 - 2 keys selected.
INFO: 2014-08-06 22:17:59 - Migrating records (1 to 2) into table sys_dictionary
INFO: 2014-08-06 22:17:59 - Records (1 to 2) into table sys_dictionary migrated
INFO: 2014-08-06 22:17:59 - Inserting records into table sys_dictionary finished (2 records inserted)
INFO: 2014-08-06 22:17:59 - Updating records in table sys_dictionary
INFO: 2014-08-06 22:17:59 - No update performed, synchronization executed for the first time
INFO: 2014-08-06 22:17:59 - Deleting records from table sys_dictionary
INFO: 2014-08-06 22:17:59 - No delete performed, synchronization executed for the first time
INFO: 2014-08-06 22:17:59 - Finished executing synchronization successfully.

  • 404 - Could not find the synchronization, history or the log.

3. Error handling

If API call ends with an error REST API will return proper HTTP Response code and explanation of what happened in response body.

Response Codes:

  • 400 - Response code 400 (and generally all 4xx codes) indicates that there is something wrong with a request (for example missing, invalid or unsupported value of a field in request body).

  • 500 - Response code 500 (and generally all 5xx codes) indicates that there is something wrong with SnowMirror which prevents the request to be fulfilled. If this happens SnowMirror log files will contain more details about the error.

    Sample Response Body for 500 Error (Content-Type: application/json):

    {
    "message": "Internal Server Error"
}

3.1. Field value validation errors

When issuing a request with request body SnowMirror validates all the fields it that request. If a value is invalid then response body will contain description of all failed validations and HTTP Response code will be

Sample "400 - Bad Request" Response Body (Content-Type: application/json):

{
    "errors": [
        {
            "field": "sync.name",
            "message": "The name of the synchronization is already used."
        },
        {
            "field": "sync.mirrorTable",
            "message": "This table name is already used by another synchronization."
        }
    ]
}

3.2. Content-type validation

When issuing a request with a body please make sure you also send a proper Content-Type header. If you fail to do so or if you provide a type SnowMirror does not support you would end up with following error.

Sample "415 - Unsupported Media Type" Response (Content-Type: application/json):

{
    "message": "Unsupported Media Type"
}

4. Authentication and Security

To use SnowMirror REST API you have to authenticate yourself. We support basic HTTP authentication.

4.1. Basic Authentication

Basic HTTP Authentication is a mechanism where you provide your credentials through HTTP request header. The header that needs to be present is called "Authentication" and it contains a string username:password encoded by Base64 algorithm.

The "Authentication" header must be contained in all requests because REST API does not maintain any session.

  • In case the "Authentication" header is not supplied SnowMirror returns 401 - Unauthorized response. This response contains "WWW-Authenticate" header with value Basic realm="SnowMirror API". The same header will be sent if provided credentials are incorrent.

  • In case the user does not have a permission to operate on the resource SnowMirror returns 403 - Forbidden response.

    Sample 403 - Forbidden Response Body (Content-Type: application/json):

    {
    "message": "Forbidden"
}

4.2. User

To be able to use API a user has to have Api Caller role assigned. He or she also has to have a role Synchronization Reader to be able to read data. Synchronization Administrator role is needed for modification (creates, updates and deletes).

4.2.1. Setting Up User Account

  1. Login into SnowMirror under your Administrator account

  2. Go to Settings / User Management page

  3. Click Add User button

  4. Fill in all required information:

    1. Choose credentials you will use to authenticate to SnowMirror API

    2. Choose a timezone in which API will communicate with this user account.

    3. Assign Api Caller, Synchronization Reader and Synchronization Administrator roles

  5. Click Add button. A new user will be created and you will be immediately able to use SnowMirror API.

4.2.2. Timezone

All dates and times in SnowMirror are stored in UTC (Universal Coordinated Time). Each user can choose a time zone in which the dates and times will be displayed to him or her. The time zone can be changed in SnowMirror on page Setting / Profile Settings.

All dates and times inserted using Rest API are expected to be in user’s time zone. Similarly all dates and times in responses from Rest API are formated in user’s time zone.

SnowMirror REST API uses the time zone from user’s settings.