Page tree
Skip to end of metadata
Go to start of metadata

Backups can be created including one or several files, when creating a backup you can specify which files you want to include, if no files are specified then it will be a full backup including all files available, for example, all account resources such as devices, scenes, actions and also all the devices backups. Device backups are raw files that devices define, for example, a gateway/hub can backup its radio configuration or its network settings, these are extended backups to provide flexibility to restore operations over a certain type of devices. In restore operations, you can also choose to restore from one or several of the files present in a particular backup.

Backup

The example below is a create request for a new backup including only API resources.

curl 'https://api.smartenit.io/v2/backups' 
	-H 'Authorization: Bearer cFd0wGw884YLS9puTfI3LOgHXQ5Hlx....' 
	-H 'Content-Type: application/json;charset=UTF-8' 
	--data-binary '{"files":[{"type":"resource","context":"areas"},{"type":"resource","context":"devices"},{"type":"resource","context":"permissions"},{"type":"resource","context":"scenes"},{"type":"resource","context":"users"}]}'

Response:

{
	"data": {
		"updatedAt": "2016-07-13T21:56:07.652Z",
		"createdAt": "2016-07-13T21:56:07.652Z",
		"accountId": "84a4ce56f022895abd086104",
		"companyId": "7624556e196dc1f65439bd4c",
		"createdBy": {
			"user": "6104bd08ce2256f084a4a896"
		},
		"_id": "60c307c5a8549145786b8f7a",
		"state": "started",
		"files": [{
			"name": "areas.tar.bz2",
			"type": "resource",
			"context": "areas",
			"state": "created"
		}, {
			"name": "devices.tar.bz2",
			"type": "resource",
			"context": "devices",
			"state": "created"
		}, {
			"name": "permissions.tar.bz2",
			"type": "resource",
			"context": "permissions",
			"state": "created"
		}, {
			"name": "scenes.tar.bz2",
			"type": "resource",
			"context": "scenes",
			"state": "created"
		}, {
			"name": "users.tar.bz2",
			"type": "resource",
			"context": "users",
			"state": "created"
		}]
	},
	"message": "Resource successfully created"
}

The backup has started and it's being created as the status attribute shows. The client must request this backup in the future to determine if the backup has already finished processing. When the backup finishes you can request again the resource to check its status:

curl -X GET 'https://api.smartenit.io/v2/backups/60c307c5a8549145786b8f7a' 
	-H 'Authorization: Bearer cFd0wGw884YLS9puTfI3LOgHXQ5Hlx....'

Response:

{
	"data": {
		"updatedAt": "2016-07-13T21:56:07.652Z",
		"createdAt": "2016-07-13T21:56:07.652Z",
		"accountId": "84a4ce56f022895abd086104",
		"companyId": "7624556e196dc1f65439bd4c",
		"createdBy": {
			"user": "6104bd08ce2256f084a4a896"
		},
		"_id": "60c307c5a8549145786b8f7a",
		"state": "uploaded",
		"files": [{
			"name": "areas.tar.bz2",
			"type": "resource",
			"context": "areas",
			"state": "uploaded"
		}, {
			"name": "devices.tar.bz2",
			"type": "resource",
			"context": "devices",
			"state": "uploaded"
		}, {
			"name": "permissions.tar.bz2",
			"type": "resource",
			"context": "permissions",
			"state": "uploaded"
		}, {
			"name": "scenes.tar.bz2",
			"type": "resource",
			"context": "scenes",
			"state": "uploaded"
		}, {
			"name": "users.tar.bz2",
			"type": "resource",
			"context": "users",
			"state": "uploaded"
		}]
	}
}

The state will change to uploaded if no error occurred and the files list will hold the description of the files that were generated.

Backup & Upload Raw Files

Another flexible option to generate backups are the file backups. Some devices can generate backups of an inner configuration such as network settings, radio configuration or any raw binary backup that the device supports. To generate these backups the API will generate a file placeholder and will wait for the device to upload the file to a specific destination. The diagram below explains the file backups flow:

The following example will generate a backup for users and for ZigBee network of a particular device:

curl -X POST 'https://api.smartenit.io/v2/backups'
	-H 'Authorization: Bearer cFd0wGw884YLS9puTfI3LOgHXQ5Hlx....'
	-H 'Content-Type: application/json;charset=UTF-8' 
	--data-binary '{"files":[{"type":"resource","context":"users"},{"type":"device","context":"zigbee_network","deviceId":"5759a2c6fb73933d7b513bf2"}]}'

Response:

{
	"data": {
		"updatedAt": "2016-07-13T23:07:31.068Z",
		"createdAt": "2016-07-13T23:07:31.068Z",
		"accountId": "d086104ce256f084a4ab2895",
		"companyId": "d4c6dc1f656e1939b7624554",
		"createdBy": {
			"user": "abd086104ce56f084a422896"
		},
		"_id": "3ac5a8545786c9b9160c3099",
		"state": "started",
		"files": [{
			"name": "users.tar.bz2",
			"type": "resource",
			"context": "users",
			"state": "created"
		}, {
			"name": "5759a2c6fb73933d7b513bf2_zigbee_network.tar.bz2",
			"type": "device",
			"context": "zigbee_network",
			"deviceId": "5759a2c6fb73933d7b513bf2",
			"state": "created"
		}]
	},
	"message": "Resource successfully created"
}

This will send a backup command to the device, when the device completes the generation of the compressed backup file, it can use a request like the following example to upload the file. This will return the updated backup record indicating the state of the files.

Notice that the file upload requires a name attribute with the same name of the file generated on the backup record, you must send this name so the API can update the placeholder with the file that is being uploaded. In the example the name of the file is "5759a2c6fb73933d7b513bf2_zigbee_network.tar.bz2"
curl -X POST 'https://api.smartenit.io/v2/backups/3ac5a8545786c9b9160c3099/upload' 
	-H 'Authorization: Bearer cFd0wGw884YLS9puTfI3LOgHXQ5Hlx....' 
	--data-binary $'
		------WebKitFormBoundarysCDeuOcyFRXu8AzY
		Content-Disposition: form-data; name="file"; filename="generated_zigbee_network_backup.tar.bz2"
		Content-Type: application/x-bzip2
 
		------WebKitFormBoundarysCDeuOcyFRXu8AzY
		Content-Disposition: form-data; name="name"
 
		5759a2c6fb73933d7b513bf2_zigbee_network.tar.bz2
		------WebKitFormBoundarysCDeuOcyFRXu8AzY--'

Response

{
	"data": {
		"updatedAt": "2016-07-13T23:07:31.068Z",
		"createdAt": "2016-07-13T23:07:31.068Z",
		"accountId": "d086104ce256f084a4ab2895",
		"companyId": "d4c6dc1f656e1939b7624554",
		"createdBy": {
			"user": "abd086104ce56f084a422896"
		},
		"_id": "3ac5a8545786c9b9160c3099",
		"state": "uploaded",
		"files": [{
			"name": "users.tar.bz2",
			"type": "resource",
			"context": "users",
			"state": "uploaded"
		}, {
			"name": "5759a2c6fb73933d7b513bf2_zigbee_network.tar.bz2",
			"type": "device",
			"context": "zigbee_network",
			"deviceId": "5759a2c6fb73933d7b513bf2",
			"state": "uploaded"
		}]
	}
}

Restore

Now that the backup is generated a restore operation can be done using the /restore endpoint. You can choose to restore one or more files inside a backup object, the following example creates a restore operation only for user records inside the backup:

Notice that you can restore one or more resources present in the backup.
A Restore operation will update or insert resources contained in the backup, it will not overwrite new data.
curl -X POST 'https://api.smartenit.io/v2/restore' 
	-H 'Authorization: Bearer cFd0wGw884YLS9puTfI3LOgHXQ5Hlx....'
	-H 'Content-Type: application/json;charset=UTF-8' 
	--data-binary '{"backupId":"60c307c5a8549145786b8f7a","files":[{"name":"users.tar.bz2","type":"resource","context":"users","state":"uploaded"}]}'

Response:

{
	"data": {
		"updatedAt": "2016-07-13T22:03:54.217Z",
		"createdAt": "2016-07-13T22:03:54.217Z",
		"backupId": "60c307c5a8549145786b8f7a",
		"accountId": "84a4ce56f022895abd086104",
		"companyId": "7624556e196dc1f65439bd4c",
		"createdBy": {
			"user": "6104bd08ce2256f084a4a896"
		},
		"_id": "9160bacac35786ac5a854078",
		"state": "started",
		"files": [{
			"name": "users.tar.bz2",
			"type": "resource",
			"context": "users",
			"state": "uploaded"
		}]
	},
	"message": "Resource successfully created"
}

The restore operation will start and the client has to check the resource again to see if the restore operation has finished:

curl -X GET 'https://api.smartenit.io/v2/restore/9160bacac35786ac5a854078' 
	-H 'Authorization: Bearer cFd0wGw884YLS9puTfI3LOgHXQ5Hlx....'

Response:

{
	"data": {
		"updatedAt": "2016-07-13T22:03:54.217Z",
		"createdAt": "2016-07-13T22:03:54.217Z",
		"backupId": "60c307c5a8549145786b8f7a",
		"accountId": "84a4ce56f022895abd086104",
		"companyId": "7624556e196dc1f65439bd4c",
		"createdBy": {
			"user": "6104bd08ce2256f084a4a896"
		},
		"_id": "9160bacac35786ac5a854078",
		"state": "restored",
		"files": [{
			"name": "users.tar.bz2",
			"type": "resource",
			"context": "users",
			"state": "restored"
		}]
	}
}

When the state changes to "restored" then the backup has been restored and all the resources data was updated.

Restore Raw Files

Restoring files that are backups of devices configuration or any other binary backup, requires device interaction. When you trigger a restore operation the API sends a restore command to the device so the device can start a local restore process like the following diagram:

 

A request to restore a device file and also resources backup, will look like the following example:

curl -X POST 'https://api.smartenit.io/v2/restore'
	-H 'Authorization: Bearer cFd0wGw884YLS9puTfI3LOgHXQ5Hlx....'
	-H 'Content-Type: application/json;charset=UTF-8' 
	--data-binary '{"backupId":"9160bacac35786ac5a854078","files":[{"name":"users.tar.bz2","type":"resource","context":"users","state":"uploaded"},{"name":"5759a2c6fb73933d7b513bf2_zigbee_network.tar.bz2","type":"device","context":"zigbee_network","deviceId":"5759a2c6fb73933d7b513bf2","state":"uploaded"}]}'

Response

{
	"data": {
		"updatedAt": "2016-07-13T23:26:43.912Z",
		"createdAt": "2016-07-13T23:26:43.912Z",
		"backupId": "9160bacac35786ac5a854078",
		"accountId": "84a4ce56f022895abd086104",
		"companyId": "7624556e196dc1f65439bd4c",
		"createdBy": {
			"user": "6104ce56f084a4abd0822896"
		},
		"_id": "1605549786ce33ac5a8c309a",
		"state": "started",
		"files": [{
			"name": "users.tar.bz2",
			"type": "resource",
			"context": "users",
			"state": "uploaded"
		}, {
			"name": "5759a2c6fb73933d7b513bf2_zigbee_network.tar.bz2",
			"type": "device",
			"context": "zigbee_network",
			"state": "restore_command_sent_to_device"
		}]
	},
	"message": "Resource successfully created"
}

Once the device downloads the specified file "5759a2c6fb73933d7b513bf2_zigbee_network.tar.bz2" and executes locally the restore process then it will notify the API about the process, if you request the restore record again you will see the updated value in the file.

curl -X GET 'https://api.smartenit.io/v2/restore/1605549786ce33ac5a8c309a'
	-H 'Authorization: Bearer cFd0wGw884YLS9puTfI3LOgHXQ5Hlx....'

Response

{
	"data": {
		"updatedAt": "2016-07-13T23:26:43.912Z",
		"createdAt": "2016-07-13T23:26:43.912Z",
		"backupId": "9160bacac35786ac5a854078",
		"accountId": "84a4ce56f022895abd086104",
		"companyId": "7624556e196dc1f65439bd4c",
		"createdBy": {
			"user": "6104ce56f084a4abd0822896"
		},
		"_id": "1605549786ce33ac5a8c309a",
		"state": "restored",
		"files": [{
			"name": "users.tar.bz2",
			"type": "resource",
			"context": "users",
			"state": "restored"
		}, {
			"name": "5759a2c6fb73933d7b513bf2_zigbee_network.tar.bz2",
			"type": "device",
			"context": "zigbee_network",
			"state": "restored"
		}]
	}
}
  • No labels