API Reference

This guide describes the HTTP REST APIs for Lucidworks Managed Search and gives examples of their use.

Overview of APIs

Lucidworks Managed Search has the following RESTful APIs.

To obtain HTTP request URIs, prepend https://pg01.us-west1.cloud.lucidworks.com/managed/api/ to the endpoints shown. For example, the HTTP request URI for the endpoint customers/customerId/tasks/ is https://pg01.us-west1.cloud.lucidworks.com/managed/api/customers/customerId/tasks/.

Clusters

Method Use

Clusters
Endpoint: customers/customerId/clusters

GET

Get a list of all Solr clusters.

POST

Create a Solr cluster.

A specific cluster
Endpoint: customers/customerId/clusters/clusterId

GET

Get information about a Solr cluster.

PUT

Modify one or more attributes of a Solr cluster. The operation is atomic; either all attributes are updated or none of them are (if the operation fails).

PATCH

Modify one or more attributes of a Solr cluster. Unlike with PUT, the values of optional attributes that aren’t specified in the PATCH command remain unchanged.

DELETE

Delete a Solr cluster.

Regions

The Regions API uses the request header x-lw-region in conjunction with the Clusters API to:

  • Specify where a resource is created

  • Modify resources in a region

  • Delete resources in a region

  • Check the status of resources in a region

Collections

Method Use

Collections
Endpoint: customers/customerId/clusters/clusterId/collections

GET

Get a list of collections.

POST

Create a collection.

A specific collection
Endpoint: customers/customerId/clusters/clusterId/collections/collectionName

GET

Get information about a collection.

PUT

Modify one or more attributes of a collection. The operation is atomic; either all attributes are updated or none of them are (if the operation fails).

PATCH

Modify one or more attributes of a collection.

DELETE

Delete a collection.

Backups

Method Use

All backups
Endpoint: customers/customerId/backups/

GET

Get a list of all backups for collections in a cluster.

POST

Back up of a collection.

DELETE

Delete all backups of collections in a cluster.

A specific backup
Endpoint: customers/customerId/backups/backupId

GET

Get information about a specific backup.

POST

Restore a collection from a specific backup.

DELETE

Delete a specific backup.

Tasks

Method Use

All tasks
Endpoint: customers/customerId/tasks/

GET

Get a list of tasks for long-running operations, such as creating or deleting clusters. Optionally, you can use a query string to limit the size of the list by the number of tasks (count), an earliest time (after), or both. By default, the list is limited to the 100 most recent tasks.

A specific task
Endpoint: customers/customerId/tasks/taskId

GET

Get the status of a specific task for a long-running operation, such as creating or deleting a cluster.

Specifying parameters

You specify parameters in Managed Search and Solr API commands in one or more of three ways:

  • In the names of URI path segments – Some path segments in request URIs take different values, for example, to distinguish clusters by the clusterId. The path segment names in this request URI that vary are in a bold italic font:

    https://pg01.us-west1.cloud.lucidworks.com/managed/api/customers/customerId/clusters/clusterId
  • In query strings – A query string follows a question mark after the path in the URI. The query string assigns values to one or more parameters. It consists of one or more field-value pairs, separated by ampersands. This request URI includes the query string q=computers, indicated in a bold font:

    https://pg01.us-west1.cloud.lucidworks.com/managed/api/acme-corp/cluster-1/solr/collection-1/select&q=computers
  • In request bodies – A message body in JSON format contains the parameters.

    curl "https://pg01.us-west1.cloud.lucidworks.com/managed/api/customers/lucidworks/clusters" -H "accept: application/json" -H "Content-Type: application/json" -H "Authorization: Bearer access-token" -d '{ "id": "jeff-1", "nodeCount": 2, "nodeType": "standard.small", "storageSizeGB": 20, "description": "test cluster", "maintenanceTimeFrame": "SUNDAY,21:45"}'

Getting the results of operations that take time

Managed Search operations take varying amounts of time. For operations that will take a while (for example cluster creation, which takes on the order of minutes) and others that might take a while, Managed Search creates tasks.

Getting information about operations for which tasks are created, for example, a POST request to create a cluster, is a several-step process:

  1. Use a REST API to submit the request.

    Managed Search creates a task to perform the operation. The body of the response to the initial request contains a taskId.

  2. (Iterative polling) Use the GET method with the tasks/taskId URI to get information about the progress of the task. Iterate until the JSON key status has the value completed. Statuses are submitted, completed (which indicates successful completion), and failed. There is also a progress key. The progress starts at 0 and reaches 100 when the operation the task performs has finished.

  3. Use a GET REST API request with the appropriate HTTP request URI to get the information you seek.

You can also use an iterative polling approach to confirm the completion of an operation before performing an operation that depends on the first operation. For example, confirm that cluster creation is complete before attempting to create collections in the cluster.

Requests

To perform Managed Search operations, submit requests to the Managed Search REST API.

In the API examples, we use curl to send the HTTP requests. The curl software supplies the HTTP methods GET and POST as defaults, depending on the options present. For clarity in the examples, we mention which methods are omitted.

Request header fields

The request header of a request to a Managed Search REST API is where you provide an OAuth2 access token (in the Authorization header field), and possibly other instructions to the Managed Search service in other header fields.

Note
For SolrJ clients, the OAuth2HttpRequestInterceptor implementation in the Lucidworks Managed Search SolrJ client library simplifies the process of obtaining, using, and refreshing access tokens.

Request header field Use

accept: application/json

Media type that the client will accept for the response body. The only supported media type is application/json.

Authorization: Bearer access-token

OAuth2 access token needed to authenticate the request

Content-Type: application/json

Media type of the request body. The only supported media type is application/json.

Example request

This curl example for creating a cluster includes header fields specified with -H flags. The OAuth2 access token is passed via the environment variable MSTOKEN, and the JSON specification for the characteristics of the cluster is obtained from create-cluster-body.json.

curl -vs -XPOST "https://pg01.us-west1.cloud.lucidworks.com/managed/api/customers/lucidworks/clusters" -H "accept: application/json" -H "Content-Type: application/json" -H "Authorization: Bearer ${MSTOKEN}" -d @create-cluster-body.json

Responses

A response message consists of a status line, response header fields, and in some cases a response body.

Tip
HTTP responses from Managed Search can be so long that they exceed the command-length limits of shells (in which case the shells truncate the output). During app development and testing, you might want to write HTTP responses to files.

Status line

The first line of a response message is the status line. The status line contains an HTTP status code and a reason phrase.

This is an example of a status line:

HTTP/1.1 200 OK

Success status codes you might get are 200, 201, 202, and 204.

Error status codes you might get include 401, 403, and 404.

Response header fields

Response header field Use

date

Date and time when the message originated.

content-type

Media type of the body of the response message.

This is an example of a response header.

date: Fri, 30 Aug 2019 16:58:49 GMT
content-type: application/json;charset=utf-8

Response body

A response body from Managed Search contains a JSON object. This is an example of a response body when getting information about the cluster test:

{
  "id": "test",
  "nodeCount": 2,
  "nodeType": "standard.small",
  "storageSizeGB": 20,
  "description": "Jeff test cluster",
  "maintenanceTimeFrame": "SUN 00:00",
  "version": "8.2.0",
  "autoscaling": {
    "enabled": false,
    "minNodes": 0,
    "maxNodes": 0,
    "targetSearchRate": 0
  },
  "enableBackups": true,
  "customerId": "lucidworks",
  "address": "https://pg01.us-west1.cloud.lucidworks.com/lucidworks/test-4/solr/",
  "status": "ready"
}

Example response

This is an example of the entire response when getting information about the cluster test:

HTTP/1.1 200 OK
date: Fri, 30 Aug 2019 16:58:49 GMT
content-type: application/json;charset=utf-8
{"id":"test","nodeCount":2,"nodeType":"standard.small","storageSizeGB":20,"description":"Jeff test cluster","maintenanceTimeFrame":"SUN 00:00","version":"8.2.0","autoscaling":{"enabled":false,"minNodes":0,"maxNodes":0,"targetSearchRate":0},"enableBackups":true,"customerId":"lucidworks","address":"https://pg01.us-west1.cloud.lucidworks.com/lucidworks/test-4/solr/","status":"ready"}