Provisioning API – Backup/Restore

Overview

The SearchStax Managed Search service provides an API supporting the creation, deletion and management of Solr Cloud deployments.

Platinum and Platinum Plus Clients Only!

The SearchStax API suite is available to our Platinum and Platinum Plus clients only, as noted on our Pricing page.

This page describes how to perform backup and restore operations through API methods.

The API can be accessed through any tool that assembles HTTP requests and dispatch them to a server. Among these would be the Python coreapi package, the Postman tool, and cURL. For Windows, use PowerShell 7+.

Account Owner, Admin, or Technical Contact

To run the SearchStax Provisioning API, you must be the account Owner, an account Admin, or a Technical Contact. See SearchStax User Roles.

Symbols enclosed in carets (< and >) such as <username> are metavariables. Substitute your local values when you encounter them in the examples.

Contents:

Related Pages:

Account-Level Methods

Backup files do not disappear when you delete the associated deployment. However, the deployment’s ssID (ss123456) becomes invalid, making it impossible to use the deployment-level methods to restore or delete the orphaned backup files.

The following three methods let us list, restore, and delete orphaned backup files from the API.

account > backup > list

This method lists the existing backups of an account, including any orphaned backup files.

GET /api/rest/v2/account/<account_name>/backup/

where <account_name> is the name of the tenant account.

This method uses Token authentication.

There is no request body.

When invoked from Linux (Bash script):

curl --request GET "https://app.searchstax.com/api/rest/v2/account/<account_name>/backup/" 
  --header "Authorization: Token <token>"

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"

$BACKUPS = Invoke-RestMethod -Method Get -ContentType 'application/json' -Headers $headers `
              -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/backup/"
$BACKUPS = $BACKUPS | ConvertTo-Json

A successful response contains a JSON object containing a list of backups:

[
    {
      "id": 57198,
      "backup_type": "One time",
      "created": "2020-06-19 04:49:42 PM (2020-06-19 16:49:42 UTC)",
      "status": "Done",
      "size": 223608,
      "region": "US West (N. California)",
      "collections": null,
      "deployment_uid": "ss305854",
      "deployment_name": "QuickStart",
      "version": "8.3.1",
      "cloud": "aws",
      "size_display": "223.61 KB",
      "replication_region": "-",
      "error_message": []
    }
]

account > backup > delete

This method deletes a backup from a deployment.

DELETE /api/rest/v2/account/<account_name>/backup/<buid>/

where <account_name> is the name of the tenant account, and <buid> is the ID of the backup.

This method uses Token authentication.

There is no request body.

When invoked from Linux (Bash script):

curl --request DELETE "https://app.searchstax.com/api/rest/v2/account/<account_name>/backup/<buid>/" 
  --header "Authorization: Token <token>"

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$BUID = "27004"

$BACKUPS = Invoke-RestMethod -Method Delete -ContentType 'application/json' -Headers $headers `
              -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/backup/$BUID/"
$BACKUPS = $BACKUPS | ConvertTo-Json

A successful response returns a 204 code and an empty string.

account > restore > create

This method restores an orphan backup file to a deployment. See also account > deployment > restore > create for more versatile restore options.

Parallel Restoration

Note that restoring a backup takes all collections offline until the restore is complete.

The parallel_restore parameter reduces restore time by rebuilding each collection in a separate thread.

Downtime due to a restore is difficult to estimate, ranging from minutes to hours for very large backup files. Experience must be your guide.

POST https://app.searchstax.com/api/rest/v2/account/<account_name>/restore/

where <account_name> is the name of the tenant account.

This method uses Token authentication.

The request body should be a “application/json” encoded object, containing the following items:

{
    id="27004"
    target_deployment_id="ss123456"
    parallel_restore="true"
}
Parameter Description Example
id
required
string		 The backup id number, from the List Backups method. “27004”
target_deployment_uid
optional
string		 The target deployment ID number. “ss123456”
parallel_restore
optional
string		 Optional ability to restore collections in parallel (multiple threads). Default is “false.” “true”

When invoked from Linux (Bash script):

curl --request POST "https://app.searchstax.com/api/rest/v2/account/<account_name>/restore/" 
  --header "Content-Type: application/json" 
  --header "Authorization: Token <token>" 
  --data '{"id":"27004","target_deployment_uid":"ss123456"}'

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"

$body = @{
    id='27004'
    target_deployment_uid='ss123456'
}

$body = $body | ConvertTo-Json

$RESULT = Invoke-RestMethod -Method Post -body $body -ContentType 'application/json' -Headers $headers `
         -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/restore/" 
$RESULT = $RESULT | ConvertTo-Json

The response is a JSON document confirming that the restore has been scheduled.

{
  "message": "restore begun"
}

Deployment-Level Methods

The SearchStax Provisioning API includes methods for performing backup and restore operations. If the backup file has been “orphaned” by deleting the source deployment, use the account-level methods instead.

account > deployment > backup > list

This method lists the existing backups of a deployment.

GET /api/rest/v2/account/<account_name>/deployment/<uid>/backup/

where <account_name> is the name of the tenant account, and <uid> is the ID of the deployment.

This method uses Token authentication.

There is no request body.

When invoked from Linux (Bash script):

curl --request GET "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/backup/" 
  --header "Authorization: Token <token>"

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$uid = "ss123456"

$BACKUPS = Invoke-RestMethod -Method Get -ContentType 'application/json' -Headers $headers `
              -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/deployment/$uid/backup/"
$BACKUPS = $BACKUPS | ConvertTo-Json

A successful response contains a JSON object containing a list of backups:

[
   {
     "id": 26919,
     "backup_type": "onetime",
     "created": "2019-11-14T17:22:22Z",
     "status": "done",
     "size": 210553,
     "region": "Amazon Web Services - us-west-1"
   }
]

account > deployment > backup > create

This method makes a one-time backup of a deployment. 

POST https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/backup/

where <account_name> is the name of the tenant account, and <uid> is the ID of the deployment.

This method uses Token authentication.

The request body should be a “application/json” encoded object, containing the following items:

{
    region: "us-west-1",
    collections: "[filmcollection]"
}
ParameterDescriptionExample
region
optional
string		The region ID of the region where the backup should be created. Defaults to the deployment’s region. Region codes can be obtained using the List Plans method or from the deployment’s description in the SearchStax dashboard. “us-west-2”
collections
optional
list		List of collections to back up – [] to back up all collectionsBash: [“collection1”, “collection2”]

PowerShell: @(‘collection1’, ‘collection2’)

When invoked from Linux (Bash script):

curl --request POST "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/backup/" 
  --header "Content-Type: application/json" 
  --header "Authorization: Token <token>" 
  --data '{"region":"us-west-1","collection":"[filmcollection]"}'

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$uid = "ss123456"

$body = @{
    region='us-west-1'
    collections=@('filmcollection')
}

$body = $body | ConvertTo-Json

$RESULT = Invoke-RestMethod -Method Post -body $body -ContentType 'application/json' -Headers $headers `
         -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/deployment/$uid/backup/" 
$RESULT = $RESULT | ConvertTo-Json

The response is a JSON document containing the description of the new backup.

{
  "id": 123456,
  "created": "2019-11-14T19:20:45.903037Z",
  "status": "pending",
  "size": 0,
  "region": "Amazon Web Services - us-west-1"
  "collections": [
     "filmcollection"
     ]
}

account > deployment > backup > delete

This method deletes a backup from a deployment.

DELETE /api/rest/v2/account/<account_name>/deployment/<uid>/backup/<buid>/

where <account_name> is the name of the tenant account, <uid> is the ID of the deployment, and <buid> is the ID of the backup.

This method uses Token authentication.

There is no request body.

When invoked from Linux (Bash script):

curl --request DELETE "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/backup/<buid>/" 
  --header "Authorization: Token <token>"

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$uid = "ss123456"
$BUID = "27004"

$BACKUPS = Invoke-RestMethod -Method Delete -ContentType 'application/json' -Headers $headers `
              -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/deployment/$uid/backup/$BUID/"
$BACKUPS = $BACKUPS | ConvertTo-Json

A successful response is a JSON document containing a confirmation message:

{
  "message": "Successfully deleted backup 27004",
  "success": "true"
}

account > deployment > backup > schedule > list

This method lists the existing backup schedules of a deployment.

GET /api/rest/v2/account/<account_name>/deployment/<uid>/backup/schedule/

where <account_name> is the name of the tenant account, and <uid> is the ID of the deployment.

This method uses Token authentication.

There is no request body.

When invoked from Linux (Bash script):

curl --request GET "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/backup/schedule/" 
  --header "Authorization: Token <token>"

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$uid = "ss123456"

$BACKUPS = Invoke-RestMethod -Method Get -ContentType 'application/json' -Headers $headers `
              -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/deployment/$uid/backup/schedule/"

$BACKUPS = $BACKUPS | ConvertTo-Json

A successful response contains a JSON object containing a list of backups:

[
  {
    "id": 1234,
    "days": [
      "mon",
      "tue",
      "wed",
      "thu",
      "fri",
      "sat",
      "sun"
    ],
    "time": "00:00:00",
    "retention": 1,
    "collections": []
  }
]

account > deployment > backup > schedule > create

This method creates a backup schedule for a deployment. 

POST https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/backup/schedule/

where <account_name> is the name of the tenant account, and <uid> is the ID of the deployment.

This method uses Token authentication.

The request body should be a “application/json” encoded object, containing the following items:

{
    "retention":  7,
    "days":  [
                 "mon",
                 "wed",
                 "fri"
             ],
    "region_id":  "us-west-1",
    "frequency":  6,
    "collections":  [
                        "filmcollection"
                    ],
    "time":  "07:00"
}
ParameterDescriptionExample
time
optional
string		Time (UTC) the backup should run. (Format: HH:MM)
Either time or frequency must be provided. 		“07:00”
days
required list
List of days on which backup should run. [“mon”, “tue”, “wed”, “thu”, “fri”, “sat”, “sun”]

[“everyday”]
retention
required number		Number of days to retain the backup.7
frequency
optional
number
At what interval (hours) the backups should run in the day.
Either time or frequency must be provided. 		3
region_id
required
string		The region ID of the region where the backup should be created. Defaults to the deployment’s region.
Region codes can be obtained using the List Plans method or from the deployment’s description in the SearchStax dashboard. 		“us-west-1”
collections
optional
list		List of collections to back up. Defaults to [] to back up all collectionsBash: [“collection1”, “collection2”]

PowerShell: @(‘collection1’, ‘collection2’)

When invoked from Linux (Bash script):

curl --request POST "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/backup/schedule/" 
  --header "Content-Type: application/json" 
  --header "Authorization: Token <token>" 
  --data '{"time":"08:30","collections":["filmcollection"],"days":["everyday"],"retention":"7","region_id":"us-west-1"}'

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$uid = "ss123456"

$body = @{
    days=@('mon', 'wed', 'fri')
    time='07:00'
    frequency=6
    retention=7
    region_id='us-west-1'
    collections=@('filmcollection')
}

$body = $body | ConvertTo-Json

$RESULT = Invoke-RestMethod -Method Post -body $body -ContentType 'application/json' -Headers $headers `
         -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/deployment/$uid/backup/schedule/" 
$RESULT = $RESULT | ConvertTo-Json

The response is a JSON document confirming success.

{
  "message": "Backup Scheduled Successfully"
}

account > deployment > backup > schedule > delete

This method deletes a backup schedule from a deployment.

DELETE /api/rest/v2/account/<account_name>/deployment/<uid>/backup/schedule/<buid>/

where <account_name> is the name of the tenant account, <uid> is the ID of the deployment, and <buid> is the ID of the backup.

This method uses Token authentication.

There is no request body.

When invoked from Linux (Bash script):

curl --request DELETE "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/backup/schedule/<buid>/" 
  --header "Authorization: Token <token>"

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$uid = "ss123456"
$BUID = "27004"

$BACKUPS = Invoke-RestMethod -Method Delete -ContentType 'application/json' -Headers $headers `
              -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/deployment/$uid/backup/schedule/$BUID/"
$BACKUPS = $BACKUPS | ConvertTo-Json

A successful response is a JSON document containing a confirmation message:

{
  "success": "The backup schedule has been deleted!"
}

account > deployment > restore > create

This method restores a backup to a deployment. Optionally, it can restore one or more individual collections from a multi-collection backup.

Restoring Individual Collections

This method can be used to restore one or more individual collections from a multi-collection backup to a multi-collection deployment. Note that restoring individual collections takes all collections offline until the restore is complete.

The parallel_restore parameter reduces restore time by rebuilding each collection in a separate thread.

Downtime due to a restore is difficult to estimate, ranging from minutes to hours for very large backup files. Experience must be your guide.

POST https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/restore/

where <account_name> is the name of the tenant account, and <uid> is the ID of the deployment.

This method uses Token authentication.

The request body should be a “application/json” encoded object, containing the following items:

{
    backup_id="27004"
    replication_factor="3"
    collection_name="quickstart"
    collections=["Col1", "Col2", "Col3"]
    parallel_restore="true"
}
Parameter Description Example
backup_id
required
string		 The backup id number, from the List Backups method. “27004”
replication_factor
optional
string		 Defaults to the number of nodes in the target cluster. You may ask for fewer replicas, but not for more. “2”
collection_name
optional
string		 [Deprecated.] Optional name of a single collection to restore. “quickstart”
collections
optional
list		 [Preferred.] Optional list of collection names to restore. [“Col1”, “Col2”, “Col3”]
parallel_restore
optional
string		 Optional ability to restore collections in parallel (multiple threads). Default is “false.” “true”

If collection_name and collections are both present, the method will restore all of the listed collections.

If collection_name and collections are both absent, the method will restore all the collections in the backup file, overwriting all previous data on the deployment.

When invoked from Linux (Bash script):

curl --request POST "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/restore/" 
  --header "Content-Type: application/json" 
  --header "Authorization: Token <Token>" 
  --data '{"backup_id":"12345678","collections":["collection1","collection3"]}'

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$uid = "ss123456"

$list = @("collection1","collection3")

$body = @{
    backup_id='12345678'
    collections=$list
}

$body = $body | ConvertTo-Json

$RESULT = Invoke-RestMethod -Method Post -body $body -ContentType 'application/json' -Headers $headers `
         -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/deployment/$uid/restore/" 
$RESULT = $RESULT | ConvertTo-Json

The response is a JSON document confirming that the restore has been scheduled.

{
  "message": "The restore request has been successfully placed in the Task queue and will be initiated soon. You can check the status with the restore-status API"
}

When performing a partial restore, SearchStax will overwrite the restored collections while preserving any others that are present.

account > deployment > restore > status

This method reports on the status of a restore.

POST /api/rest/v2/account/<account_name>/deployment/<uid>/restore/status/

where <account_name> is the name of the tenant account, <uid> is the ID of the deployment.

This method uses Token authentication.

There is no request body.

When invoked from Linux (Bash script):

curl --request POST "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/restore/status/" 
  --header "Authorization: Token <token>"

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$uid = "ss123456"

$RESULTS = Invoke-RestMethod -Method Post -ContentType 'application/json' -Headers $headers `
              -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/deployment/$uid/restore/status/"
$RESULTS = $RESULTS | ConvertTo-Json

The response is a JSON object containing an appropriate message string:

{
  "message": "Backup Restore in Progress"
}

{
  "message": "No restore Running on this deployment"
}

Questions?

Do not hesitate to contact the SearchStax Support Desk.