SearchStax API - DNS Alias


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

This page describes how to redirect a DNS alias from one deployment to another using the API.

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:

DNS Alias

SearchStax provides the ability to set up a DNS CNAME alias for your deployment. This means that your search application can query a domain address of the form myalias.searchstax.com in place of a literal Solr HTTP Endpoint like ss123456-hemxx0ug-us-west-1-aws.searchstax.com/solr/.

We also provide API methods that let you redirect this alias to a different deployment in the same account. This lets you switch search traffic from one deployment to another in an emergency. Note that multiple CNAME records can point to the same deployment.

Searchstax controls the master list of CNAME records to prevent name collisions. If your system would benefit from a CNAME alias, please contact sales@searchstax.com.

account > dns-record > list

This method lists the existing CNAME aliases of an account.

GET /api/rest/v2/account/<account_name>/dns-record/

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

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"

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

A successful response is a JSON object containing a list of CNAME records for this account:

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "associated": true,
      "name": "alias1",
      "value": "ss123456-dbw2acz6-us-west-1-aws.searchstax.com",
      "deployment": "ss123456",
      "ttl": 300
    },
    {
      "associated": true,
      "name": "alias2",
      "value": "ss123456-jdwz6lb2-us-west-1-aws.searchstax.com",
      "deployment": "ss123456",
      "ttl": 300
    },
    {
      "associated": true,
      "name": "alias3",
      "value": "ss123456-jdwz6lb2-us-west-1-aws.searchstax.com",
      "deployment": "ss123456",
      "ttl": 300
    }
  ]
}

account > dns-record > read

This method reads a single CNAME record.

GET /api/rest/v2/account/<account_name>/dns-record/<name>/

where <account_name> is the name of the tenant account, and <name> is the name of the alias.

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

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$NAME = "alias1"

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

A successful response is a JSON object containing a single CNAME record from this account:

{
  "associated": true,
  "name": "alias3",
  "value": "ss123456-jdwz6lb2-us-west-1-aws.searchstax.com",
  "deployment": "ss123456",
  "ttl": 300
}

account > dns-record > associate

This method updates a DNS CNAME record, associating the alias with a deployment's Solr HTTP Endpoint. It can also set the DNS TTL (time to live) value for the record.

PATCH https://app.searchstax.com/api/rest/v2/account/<account_name>/dns-record/<name>/

where <account_name> is the name of the tenant account, and <name> is the name of the alias.

This method uses Token authentication.

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

{
    deployment='ss123456'
    ttl='300'
}
Parameter Description Example
deployment
required
string
The deployment ID number from the Solr HTTP Endpoint. "ss123456"
ttl
required
string
The DNS time-to-live value (seconds), which must be one of 60, 300, 900, 1800, 3600, 21600, 43200, or 86400. "300"

When invoked from Linux (Bash script):

curl --request PATCH "https://app.searchstax.com/api/rest/v2/account/<account_name>/dns-record/<name>/" \
  --header "Content-Type: application/json" \
  --header "Authorization: Token <token>" \
  --data '{"deployment":"ss123456","ttl":"300"}'

When invoked from Windows (PowerShell script):

$ACCOUNT = "AccountName"
$NAME = "alias1"

$body = @{
    deployment='ss123456'
    ttl='300'
}

$body = $body | ConvertTo-Json

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

The response is a JSON document containing the updated CNAME record.

{
  "associated": true,
  "name": "alias3",
  "value": "ss123456-jdwz6lb2-us-west-1-aws.searchstax.com",
  "deployment": "ss123456",
  "ttl": 300
}

Questions?

Do not hesitate to contact the SearchStax Support Desk.