How to Create/Restore System Backup via API

Nx Witness allows third-party developers to back up and restore their system database using the API. In this article, we provide basic code examples in Python 3 to demonstrate one method for accomplishing these tasks.

Examples and explanations for both the new API available in Nx Witness 5.0 (and newer) and the deprecated API available in Nx Witness 4.2 (and older) are provided. Refer to Server HTTP REST API for more information on our APIs and on accessing our API documentation.

Prerequisites

Authentication

Nx Witness 5.0 uses HTTP bearer/session token authentication, while Nx Witness 4.2 uses HTTP Basic and Digest authentication. We perform the API requests below as local users.

The examples in this article are based on the code in the Github repository. Refer to Nx Witness Authentication for a detailed description, where they can be found in the following sections:

• Using the deprecated API — Under “Local and LDAP Users” in the “HTTP Basic and Digest Authentication” section, refer to the code under # Step 4 and # Step 5.
• Using the new API — Under “Local and LDAP Users” in the “Recommended Authentication in "Nx Witness” section, refer to the code in main().

How to Create a System Backup

The two API requests for creating a system backup accomplish this by creating a binary dump of your system database, which you would need to capture into a file.

The two code examples below are designed to create a backup of your Nx Witness system in the form of a binary file, which will be named as systembackup_{backup_time}.db, where the {backup_time} portion will reflect the time at which the script was run.

Nx Witness 5.0 (New API)

For the new API, you will use GET​/rest​/v1​/system​/database. 

get_method_header = create_header(primary_token)

system_backup = request_api(LOCAL_URL, f'/rest/v1/system/database', 'GET', verify=False, headers=get_method_header)

delete_method_header = create_header(secondary_token)

request_api(LOCAL_URL, f'/rest/v1/login/sessions/{secondary_token}', 'DELETE', verify=False, headers=delete_method_header)

backup_time = datetime.now().strftime('%m-%d-%Y-%H-%M-%S')

with open(f'systembackup_{backup_time}.db', 'bw') as backup:
   backup.write(base64.b64decode(system_backup["data"]))

Nx Witness 4.2 (Deprecated API)

For the deprecated API, you will use GET/ec2/dumpDatabase.

def main():

  system_backup = request_api(SERVER_URL, API_URI, API_METHOD, auth=requests.auth.HTTPDigestAuth(USERNAME, PASSWORD), verify=False)

  backup_time = datetime.now().strftime('%m-%d-%Y-%H-%M-%S')

  with open(f'systembackup_{backup_time}.db', 'bw') as backup:
      backup.write(base64.b64decode(system_backup["data"]))

How to Restore a System Backup

The two API requests for restoring a system accomplish this by loading the system database from the database file that was provided in the backup request. 

The code examples below assume your system backup is in database file format. To use them, replace ‘FILENAME’ with the name of the backup file you want to restore your system database with.

After restoring the system, Nx Witness Server will restart automatically. For the changes to appear in Nx Witness Desktop, restart the client.

Nx Witness 5.0 (New API)

For the new API, you use POST​/rest​/v1​/system​/database. 

filename = 'FILENAME'  # replace FILENAME with your backup file

with open(f'{filename}', 'br') as recovery:
   recovery_file = recovery.read()
   recovery_file = json.dumps({"data": base64.b64encode(recovery_file).decode()})


get_method_header = create_header(primary_token)

request_api(LOCAL_URL, f'/rest/v1/system/database', 'POST', verify=False, headers={**get_method_header, 'Content-type':'application/json'}, data=recovery_file)

delete_method_header = create_header(secondary_token)

Nx Witness 4.2 (Deprecated API)

For the deprecated API, you use POST/ec2/restoreDatabase. 

def main():

   filename = 'FILENAME'  # replace FILENAME with your backup file

   with open(f'{filename}', 'br') as recovery:
       recovery_file = recovery.read()
       recovery_file = json.dumps({"data": base64.b64encode(recovery_file).decode()})

   request_api(SERVER_URL, API_URI, API_METHOD, auth=requests.auth.HTTPDigestAuth(USERNAME, PASSWORD), verify=False, headers={'Content-type':'application/json'}, data=recovery_file)