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:

Related Pages:

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
}
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/?page=<n>&page_size=<m>

where <account_name> is the name of the tenant account; page (optional) is the page number of a multi-page list; and page_size (optional) is the number of deployments to include on a page.

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. Note that next and previous are literal URLs that fetch the next and previous pages of a multi-page list of deployments.

{
  "count": 20,
  "next":"https://app.searchstax.com/api/rest/v2/account/<accountName>/deployment/?page=3&page_size=5",
  "previous":"https://app.searchstax.com/api/rest/v2/account/<accountName>/deployment/?page_size=5",
  "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 –

KeyValueExample
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 aboutCloud providerRegion IDAdditional application node pricePriceCloud provider IDAdditional 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 accountfalse

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.

Was this article helpful?
YesNo