Solr Rest API Deployment - SearchStax


Overview

SearchStax® by Measured Search® provides an API supporting the creation and deletion of SearchStax deployments. 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.

Examples using cURL are presented on this page. There is also an interactive page of coreapi examples.

Most of the API is devoted to helper functions that expose parameters required by the create and delete operations. These functions are presented first in the order you would utilize them. The create and delete functions are the final examples on the page.

API Permissions and Termination Protection

The users associated with a SearchStax account can be allocated create, delete, and read permissions to use the SearchStax API on the deployments of that account.

Select the API Permissions page from the navigation column on the left margin of the SearchStax dashboard. This page shows the authorized users of the current account. Check the boxes of the appropriate permissions.

SearchStax User API Permissions

It is possible to shield specific deployments from API deletion. On the Deployment Details page, look for API Termination Protection. Click the lock icon to protect the deployment from API deletion. SearchStax API Termination Protection Lock This lock gives the Admin some peace of mind while developers experiment with the API.

Host and Resource Path

The SearchStax API appends keywords and parameters to this base URL:

https://searchstax.measuredsearch.com/

Request Authorization Token

The first step in using the SearchStax API is to obtain an authentication token by logging in to the SearchStax server. The token is included in subsequent API requests. It expires 60 minutes after you stop using it.

POST /api/rest/v1/obtain-auth-token/

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

Parameter Remarks
username This is the email address used when you log into the SearchStax server.
password This is the password associated with the username.

When invoked from cURL:

$ curl -H "Content-Type: application/json" -X POST -d '{"username":"user@company.com","password":"4r36%74m"}' https://searchstax.measuredsearch.com/api/rest/v1/obtain-auth-token/

The response is a JSON document containing an authorization token.

{
  "token": "aa70cb0a180a0532ae8855f7a1712eeceb81e080"
}

List Available Plans

This function generates a list of available SearchStax plans.

GET /api/rest/v1/plan/?region_id={id}&provider_id={id}&page={n}

The following parameters should be included as part of a URL query string.

Parameter Remarks
page The page number of the desired plan within the list. Optional.
region_id Filter by a specific region_id (derived from the unrestricted output). Example: "us-west-2". Optional.
provider_id Filter by a cloud provider_id (derived from the unrestricted output). Example: "aws". Optional.

When called through cURL:

$ curl -H "Content-Type: application/json" -H "Authorization: Token 8a16f2e33941d5cb9c28c0941e2231fd65e336a2" -X GET https://searchstax.measuredsearch.com/api/rest/v1/plan/?region_id=us-west-2&provider_id=aws&page=2

The response is a JSON document representing a list of all billing and cloud deployment options, or a more limited list depending on your filter settings. This is the output for a typical plan: SearchStax List Plans
Note the plan_id, which is the key that identifies a specific plan. It is used in a following function to create a new deployment.

List Deployments

The API can list the current deployments under a specific account (called a tenant_name).

GET /api/rest/v1/deployment/{tenant_name}/?page=n

The following parameters should be included in the URL path.

Parameter Remarks
tenant_name This is the name of the SearchStax account. In our examples, this account is named "DemoUser". This is not the same as the login username. Required.

SearchStax Tenant User

The following parameters should be included as part of a URL query string.

Parameter Remarks
page The page number of the desired deployment, if only one is desired. Optional.

When invoked from cURL:

$ curl -H "Content-Type: application/json" -H "Authorization: Token 8a16f2e33941d5cb9c28c0941e2231fd65e336a2" -X GET https://searchstax.measuredsearch.com/api/rest/v1/deployment/DemoUser/

The response is a JSON document containing a list of SearchStax deployments associated with the indicated account (tenant_name). SearchStax Deployment Details Note the uid attribute (the unique id), which can be used to get the details of this deployment or to delete it.

View Deployment Details

If you know the uid of a deployment, you can request its details.

GET /api/rest/v1/deployment/{tenant_name}/{uid}/

The following parameters should be included in the URL path.

Parameter Remarks
tenant_name This is the name of the SearchStax account. In our examples, this account is named "DemoUser". This is not the same as the login username. Required.
uid This is the id of the specific deployment, obtained from the list of account deployments, above. Required.

When invoked through cURL:

$ curl -H "Content-Type: application/json" -H "Authorization: Token 8a16f2e33941d5cb9c28c0941e2231fd65e336a2" -X GET https://searchstax.measuredsearch.com/api/rest/v1/deployment/DemoUser/ss676359/

The response is a JSON document describing the attributes of the indicated deployment. SearchStax Deployment Details Display

Create a Deployment

The SearchStax API lets us create a new SearchStax deployment programmatically. Note that there must be a pre-existing SearchStax account (a tenant_user). The new deployment is created inside that account.

POST /api/rest/v1/deployment/{tenant_name}/

The following parameters should be included in the URL path.

Parameter Remarks
tenant_name This is the name of the SearchStax account. In our examples, this account is named "DemoUser". This is not the same as the login username. Required.

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

Parameter Remarks
name The name of the new deployment. Required.
plan_id The id label of the requested SearchStax plan, such as "aws-us-west-2-sb1". Required.
version Version (6.1.0 for Solr or 5.2.1 for Elasticsearch). Required
additional_nodes A deployment has a default number of nodes (usually three). This is the number of nodes to add beyond the default. Optional.
standalone_zk Currently forced to 0.
skip_lb Currently forced false.
new_relic_apm Enable New Relic APM for this deployment. See the New Relic Tutorial. Optional. (true/false)
new_relic_servers Enable New Relic Servers for this deployment. Optional. (true/false)

When invoked from cURL:

$ curl -H "Content-Type: application/json" -H "Authorization: Token 8a16f2e33941d5cb9c28c0941e2231fd65e336a2" -X POST -d '{"name":"SolrFromAPI","plan_id":"aws-us-west-2-ss1","version":"6.4.2","additional_nodes":"0","standalone_zk":"0"}' https://searchstax.measuredsearch.com/api/rest/v1/deployment/DemoUser/

The API responds with a JSON document containing the uid of the new deployment.

{
    "uid": "ss134798"
}

You can view the new deployment in the list of deployments on the SearchStax dashboard: SearchStax Proof

Delete a Deployment

The SearchStax API lets us delete a deployment based on the tenant_name and the uid.

This is an HTTP DELETE request. There is no safety net. If you accidentally direct this command at the wrong deployment, it will be unmade. See API Termination Protection.

DELETE /api/rest/v1/deployment/{tenant_name}/{uid}/

The following parameters should be included in the URL path.

Parameter Remarks
tenant_name This is the name of the SearchStax account. In our examples, this account is named "DemoUser". This is not the same as the login username. Required.
uid This is the unique id of the deployment, obtained from the Deployments List, above. Required.

When invoked from cURL:

$ curl -H "Content-Type: application/json" -H "Authorization: Token 8a16f2e33941d5cb9c28c0941e2231fd65e336a2" -X DELETE  https://searchstax.measuredsearch.com/api/rest/v1/deployment/DemoUser/ss134798/

For a successful deletion, the API returns an empty JSON document.

{}

You can verify the deletion in the SearchStax dashboard: SearchStax Deployment Terminated