SearchStax API - Deployments

Overview

SearchStax^® provides an API supporting the creation, deletion and management of SearchStax deployments.

This page describes how to create and manage deployments using 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 Core 6.1+.

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:

Deployment

account > deployment > create

This method lets you create a new deployment. Note that a successful response indicates only that deployment creation was successfully authorized and has begun. It can take up to an hour to bring a new deployment on line depending on the cloud provider.

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

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:

{
    "name": "DN4_azure_api_2",
    "application": "Solr",
    "application_version": "7.3.1",
    "termination_lock": false,
    "plan_type": "DedicatedDeployment",
    "plan": "DN4",
    "region_id": "eastus",
    "cloud_provider_id": "azure",
    "num_additional_app_nodes": 0
}

Parameter	Description	Example
name required string	The name of the new deployment	"DN4_azure_api_2"
application required string	The application for which this deployment is being created.	"Solr"
application_version required string	The version of application being deployed. Detailed information regarding application versions is available from the List Plans method.	"7.3.1"
termination_lock required boolean	Whether or not the deployment should be shielded from API deletion.	false
plan_type required string	Available plan type could be Shared Deployment or Dedicated Deployment. Currently SearchStax only supports Dedicated Deployment (the default).	"DedicatedDeployment"
plan required string	The plan of the selected plan type. Detailed information regarding plans available can be fetched using List Plans method.	"DN4"
region_id required string	The region ID of the region where deployment has to be created. Detailed information regarding regions available can be fetched using List Plans method.	"eastus"
cloud_provider_id required string	The cloud provider to be used to create this deployment. Detailed information regarding cloud providers available can be fetched using List Plans method.	"aws" "azure" "gcp"
num_additional_app_nodes optional number	The number of additional nodes to be added to the deployment in case you want to add nodes to a dedicated cluster's default 3 nodes.	"0"

When invoked from Linux (Bash script):

curl --request POST "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/" \
  --header "Content-Type: application/json" \
  --header "Authorization: Token <token>" \
  --data "{
    \"name\": \"DN4_azure_api_2\",
    \"application\": \"Solr\",
    \"application_version\": \"7.3.1\",
    \"termination_lock\": false,
    \"plan_type\": \"DedicatedDeployment\",
    \"plan\": \"DN4\",
    \"region_id\": \"eastus\",
    \"cloud_provider_id\": \"azure\",
    \"num_additional_app_nodes\": \"0\"
    }"

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"

$body = @{
    name='SolrFromAPI'
    application='Solr'
    application_version='7.5.0'
    termination_lock='false'
    plan_type='DedicatedDeployment'
    plan='DN1'
    region_id='us-west-1'
    cloud_provider_id='aws'
    num_additional_app_nodes='0'
}

$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/" 
$RESULT = $RESULT | ConvertTo-Json

The response is a JSON document containing ...

{
  "name": "SolrFromAPI",
  "uid": "ss123456",
  "application": "Solr",
  "application_version": "7.5.0",
  "tier": "Silver",
  "http_endpoint": null,
  "status": "Pending",
  "provision_state": "Pending",
  "termination_lock": false,
  "plan_type": "DedicatedDeployment",
  "plan": "DN1",
  "region_id": "us-west-1",
  "cloud_provider": "Amazon Web Services",
  "cloud_provider_id": "aws",
  "num_additional_app_nodes": 0,
  "deployment_type": "Dedicated Node",
  "num_nodes_default": 1,
  "num_zookeeper_nodes_default": 0,
  "num_additional_zookeeper_nodes": 0,
  "servers": [],
  "zookeeper_ensemble": null,
  "tag": [],
  "specifications": {
    "disk_space": "8589934592",
    "jvm_heap_memory": "536870912",
    "physical_memory": "1073741824"
  }
}

Note that the servers and the zookeeper_ensemble values are not initially available because those entities take time to create. Wait until the deployment is up and running, and then use the account > deployment > list method (below).

account > deployment > delete

This method deletes a deployment from the tenant account. Note that a successful response means only that the deletion process was authorized and has begun. It can take up to an hour to delete a deployment depending on the cloud provider.

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

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 DELETE "https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/" \
  --header "Authorization: Token <token>"

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"

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

A success response will identify the deleted deployment.

{
  "success": "true",
  "message": "Successfully deleted ss123456"
}

Invalid UID will throw a Not Found error.

{
  "detail": "Not found."
}

Subject to Termination Lock

The Termination Lock button on the Deployment Details page in the SearchStax Dashboard protects the deployment from API deletion until the lock is released.

If the Termination Lock is set, you'll see a message like this one:

{
   "detail":"This deployment has Termination Lock enabled. Please first remove the termination lock, and then retry deleting the deployment."
}

account > deployment > list

This method lists the deployments of an account along with their deployment details.

GET https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/

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

This method uses either Token authentication or API Key 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/" \
  --header "Authorization: Token <token>"

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"

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

A successful response contains a JSON object containing a list of deployment descriptions:

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "name": "solr-7-5-dc4",
      "uid": "ss123456",
      "application": "Solr",
      "application_version": "7.5.0",
      "tier": "Silver",
      "http_endpoint": "https://ss123456-us-east-1-aws.searchstax.com/solr/",
      "status": "Running",
      "provision_state": "Done",
      "termination_lock": false,
      "plan_type": "DedicatedDeployment",
      "plan": "DC4",
      "region_id": "us-east-1",
      "cloud_provider": "Amazon Web Services",
      "cloud_provider_id": "aws",
      "num_additional_app_nodes": 0,
      "deployment_type": "Dedicated Cluster",
      "num_nodes_default": 3,
      "num_additional_zookeeper_nodes": 0,
      "servers": [
        "ss123456-3",
        "ss123456-2",
        "ss123456-1"
      ],
      "zookeeper_ensemble": "ss123456-1-us-east-1-aws.searchstax.com:2181,ss123456-2-us-east-1-aws.searchstax.com:2181,ss123456-3-us-east-1-aws.searchstax.com:2181",
      "tag": [
        "metrics-api",
        "user:dipsy"
      ],
      "specifications": {
        "disk_space": "34359738368",
        "jvm_heap_memory": "2147483648",
        "physical_memory": "4294967296"
      }
    }, <plus more deployments, if any...>

account > deployment > read

This method lists the properties of a specific deployment.

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

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>/" \
  --header "Authorization: Token <token>"

When invoked from Windows (PowerShell script):

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

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

The response is a JSON document containing the detailed properties of a deployment:

{
  "name": "Script-Testing",
  "uid": "ss123456",
  "application": "Solr",
  "application_version": "7.5.0",
  "tier": "Silver",
  "http_endpoint": "https://ss123456-v3xqvj5e-us-west-1-aws.searchstax.com/solr/
",
  "status": "Running",
  "provision_state": "Done",
  "termination_lock": false,
  "plan_type": "DedicatedDeployment",
  "plan": "NDC4",
  "region_id": "us-west-1",
  "cloud_provider": "Amazon Web Services",
  "cloud_provider_id": "aws",
  "num_additional_app_nodes": 0,
  "deployment_type": "Dedicated Cluster",
  "num_nodes_default": 2,
  "num_zookeeper_nodes_default": 3,
  "num_additional_zookeeper_nodes": 0,
  "servers": [
    "ss123456-5",
    "ss123456-4",
    "ss123456-3",
    "ss123456-2",
    "ss123456-1"
  ],
  "zookeeper_ensemble": "ss123456-v3xqvj5e-1-us-west-1-aws.searchstax.com:2181,s
s213022-v3xqvj5e-2-us-west-1-aws.searchstax.com:2181,ss123456-v3xqvj5e-3-us-west
-1-aws.searchstax.com:2181",
  "tag": [],
  "specifications": {
    "disk_space": "34359738368",
    "jvm_heap_memory": "2147483648",
    "physical_memory": "4294967296"
  }
}

Converting specifications to GB

In a PowerShell script, we can convert the reported specification values to GB using the following lines. Do not convert the output to JSON before making these calculations:

$GB = [math]::pow( 1024, 3 ) # To convert raw memory to rounded GB like the UI uses. $DISK = $DETAILS.specifications.disk_space / $GB $JVM = $DETAILS.specifications.jvm_heap_memory / $GB $MEMORY = $DETAILS.specifications.physical_memory / $GB

Write-Host "Disk space is $DISK GB" Write-Host "JVM heap memory is $JVM GB" Write-Host "Physical memory is $MEMORY GB"

account > deployment > get_deployment_health

This method gets the deployment's health using its UID.

GET https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/deployment-health/

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>/deployment-health/" \
  --header "Authorization: Token <token>"

When invoked from Windows (PowerShell script):

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

$RESULT = Invoke-RestMethod -Method Get -Headers $headers `
         -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/deployment/$uid/deployment-health/" 
$RESULT = $RESULT | ConvertTo-Json

Responses are JSON documents like those shown below. These examples are from a three-node cluster:

All nodes are running.
{ "status": "OK", "level": "success" }
One or two of the three servers is down.
{ "status": "Warn", "level": "warning" }
All three servers are down.
{ "status": "Error", "level": "danger" }
Invalid UID throws a Not Found error.
{ "detail": "Not found." }

account > deployment > collections_health

This method gets the health of a deployment's collections.

GET https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/collection-health/

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>/collections-health/" \
  --header "Authorization: Token <token>"

When invoked from Windows (PowerShell script):

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

$RESULT = Invoke-RestMethod -Method Get -Headers $headers `
         -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/deployment/$uid/collections-health/" 
$RESULT = $RESULT | ConvertTo-Json

Responses are JSON documents like those shown below.

All collections are running.
{ "success": true, "healthy": true}
One or more collections are degraded.
{ "success": true, "healthy": false }
API endpoint failure.
{ "success": false, "error": "some message" }

account > deployment > server > start_solr

This method starts an individual Solr node using its UID.

POST https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/server/<node>/start-solr/

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

This method uses either Token authentication or API Key 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>/server/<node>/start-solr/" \
  --header "Authorization: Token <token>"

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$uid = "ss123456"
$NODE = "ss123456-4"

$RESULT = Invoke-RestMethod -Method Post -Headers $headers `
         -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/deployment/$uid/server/$NODE/start-solr/" 
$RESULT = $RESULT | ConvertTo-Json

The response is a JSON document similar to this:

{
  "success": true
}

account > deployment > server > stop_solr

This method stops an individual Solr node using its UID.

POST https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/server/<node>/stop-solr/

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

This method uses either Token authentication or API Key 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>/server/<node>/stop-solr/" \
  --header "Authorization: Token <token>"

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$uid = "ss123456"
$NODE = "ss123456-4"

$RESULT = Invoke-RestMethod -Method Post -Headers $headers `
         -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/deployment/$uid/server/$NODE/stop-solr/" 
$RESULT = $RESULT | ConvertTo-Json

The response is a JSON document similar to this:

{
  "success": true
}

account > deployment > server > host_status

This method returns the status of an individual Solr node using its UID.

GET https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/server/<node>/host-status/

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

This method uses either Token authentication or API Key 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>/server/<node>/host-status/" \
  --header "Authorization: Token <token>"

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$uid = "ss123456"
$NODE = "ss123456-4"

$RESULT = Invoke-RestMethod -Method Get -Headers $headers `
         -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/deployment/$uid/server/$NODE/host-status/" 
$RESULT = $RESULT | ConvertTo-Json

The response is a JSON document similar to this:

{
  "level": "success",
  "status": "OK"
}

account > deployment > server > list

This method returns a list of nodes making up a Solr deployment.

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

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

This method uses either Token authentication or API Key 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>/server/" \
  --header "Authorization: Token <token>"

When invoked from Windows (PowerShell script):

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

$RESULT = Invoke-RestMethod -Method Get -Headers $headers `
         -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/deployment/$uid/server/" 
$RESULT = $RESULT | ConvertTo-Json

The response is a JSON document similar to this:

[
  {
    "sn": 1,
    "node": "ss123456-1",
    "private_address": "10.0.1.78",
    "dns_address": "ss123456-jkzg2pr0-1-ca-central-1-aws.searchstax.com",
    "status": "Running",
    "solr": false,
    "zookeeper": true,
    "silk": false
  },
  {
    "sn": 2,
    "node": "ss123456-2",
    "private_address": "10.0.1.74",
    "dns_address": "ss123456-jkzg2pr0-2-ca-central-1-aws.searchstax.com",
    "status": "Running",
    "solr": false,
    "zookeeper": true,
    "silk": false
  },
]

account > plan > list

This method lists the available deployment plans and the regions where those plans are available.

GET https://app.searchstax.com/api/rest/v2/account/<account_name>/plan/?1&application=solr&plan_type=DedicatedPlan

where <account_name> is the name of the tenant account. There are three query parameters: page is the page number within the paginated result set; application requests plans for either "solr" or "elasticsearch"; and plan_type is "DedicatedPlan". (The API currently supports only one plan type.)

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>/plan/?1&application=solr&plan_type=DedicatedPlan" \
  --header "Authorization: Token <token>"

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"

$RESULT = Invoke-RestMethod -Method Get -Headers $headers `
         -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/plan/?1&application=solr&plan_type=DedicatedPlan" 
$RESULT = $RESULT | ConvertTo-Json

The response is a JSON document with the following values -

Key	Value	Example
name "string"	The name of the plan	"DN4"
description "string"	The description of the plan.	"4GB memory, 32GB storage"
application "object"	JSON object with details of application selected	`{ "name": "Solr", "description": "Apache Solr", "tag": "solr" }`
application_versions "list of strings"	List of available application versions	["7.3.1", "7.2.1"]
plan_type "string"	The plan type selected	"DedicatedPlan"
plan_regions "list of objects"	List of objects containing information about Cloud provider Region ID Additional application node price Price Cloud provider ID Additional zookeeper node price	`{ "cloud_provider": "Microsoft Azure", "region_id": "centralus", "additional_application_node_price": 312, "price": 312, "cloud_provider_id": "azure", "additional_zookeeper_node_price": 0 }`
trial_available "boolean"	Whether the plan is available in trial account	false

account > usage > list

This method produces a list of an account's billable usage events during a specific year and month.

GET /api/rest/v2/account/<account_name>/usage/<year>/<month>/

where <account_name> is the name of the tenant account, <year> is an integer (2019), and <month> is an integer (1-12).

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>/usage/<year>/<month>/ \
  --header "Authorization: Token <token>"

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$YEAR = "2019"
$MONTH = "3"

$RESULTS = Invoke-RestMethod -Method Get -Headers $headers `
          -uri "https://app.searchstax.com/api/rest/v2/account/$ACCOUNT/usage/$YEAR/$MONTH/" 
$RESULTS = $RESULTS | ConvertTo-Json

The response is a JSON document containing a list of usage events like this one:

  {
    "SKU": "DN4",
    "startDate": "2019-04-01",
    "endDate": "2019-04-30",
    "objectID": "ss123456",
    "currency": "USD",
    "amount": "192.00",
    "usage": 30,
    "tagCollection": []
  },

Usage is the number of billable days between startDate and endDate, inclusively. In the case of backup storage, it is the number of bytes stored.

Questions?

Do not hesitate to contact the SearchStax Support Desk.

Free Trial

Getting Started

Integrate Solr with...

Cloud Manager

Private Cloud

Pulse/Monitoring

Search Analytics

SearchStax API

Third-Party Integration

Accounts and Billing

Support Guide

SearchStax API - Deployments

Overview

account > deployment > create

account > deployment > delete

account > deployment > list

account > deployment > read

account > deployment > get_deployment_health

account > deployment > collections_health

account > deployment > server > start_solr

account > deployment > server > stop_solr

account > deployment > server > host_status

account > deployment > server > list

account > plan > list

account > usage > list

Questions?