Managed Search API Reference

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

RESTful HTTP API concepts

Lucidworks Managed Search APIs are RESTful HTTP APIs. Applications access the API endpoints over HTTPS, which is secured by TLS.

Representational State Transfer (REST) is many things. To use a RESTful HTTP API, the key points to understand are:

  • Client-server architecture, and requests and responsesHypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing provides this information:

    "A client sends an HTTP request to a server in the form of a request message, beginning with a request-line that includes a method, URI, and protocol version (Section 3.1.1), followed by header fields containing request modifiers, client information, and representation metadata (Section 3.2), an empty line to indicate the end of the header section, and finally a message body containing the payload body (if any, Section 3.3)."

    "A server responds to a client’s request by sending one or more HTTP response messages, each beginning with a status line that includes the protocol version, a success or error code, and textual reason phrase (Section 3.1.2), possibly followed by header fields containing server information, resource metadata, and representation metadata (Section 3.2), an empty line to indicate the end of the header section, and finally a message body containing the payload body (if any, Section 3.3)."

  • HTTP headers and header fields – HTTP headers and the fields they contain convey meta-information about the request, for example by providing the OAuth2 access token.

  • HTTP request URIs (also referred to as endpoints) – These are the Web locations to which Managed Search clients direct requests. Different URIs have different uses. For example, a URI that ends in a specific clusterId is used for operations on that cluster.

  • Methods – The method in a request, usually a verb, specifies what action the server should take at the specified endpoint when it receives the request. For example, use GET to get information and POST to create a resource.

  • HTTP request body (also called the payload) – The request body is a JSON object that contains information the Managed Search servers need to perform an action. For example, a POST request to create a cluster must contain a body that specifies the nodeCount (number of Solr nodes) and nodeType (type of all Solr nodes), amongst other things.

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 (for Managed Search and Solr APIs) – 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://cloud.lucidworks.com/managed/api/customers/customerId/clusters/clusterId
  • In query strings (for Solr APIs) – A query string follows a question mark after the path in the URI. The query string consists of one or more field-value pairs, separated by ampersands. This request URI includes a query component indicated in a bold font:

    https://cloud.lucidworks.com/managed/api/acme-corp/cluster-1/solr/collection-1/select&q=computers
  • In request bodies (for Managed Search and Solr APIs) – A JSON payload contains the parameters.

    curl "https://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"}'

Overview of APIs

Lucidworks Managed Search has the following RESTful APIs:

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).

Caution
PUT replaces all optional attributes that aren’t specified with their default values. If nondefault values of optional attributes are desired, specify the desired values for those attributes. Alternatively, use PATCH.

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.

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.

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

GET

Get the status of a long-running task, such as one creating or deleting clusters

Note
Preface the API endpoints in the table with the first part of the URI path, that is, with https://cloud.lucidworks.com/managed/api For example, the full URI for the endpoint /customers/customerId/clusters would be https://cloud.lucidworks.com/managed/api/customers/customerId/clusters.

In the API examples, we use curl to send the HTTP requests. The default HTTP method for curl is GET. It is omitted from the examples that use GET.

HTTP responses from Site 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.