REST API Concepts

RESTful HTTP APIs

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

Concepts

Representational State Transfer (REST) is many things. To use a RESTful HTTP API, the key concepts 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. Both the request and the response have headers.

  • 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 – 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. This is an example of an HTTP request body for creating a small cluster:

    {
      "id": "Test-2",
      "nodeCount": 2,
      "nodeType": "standard.small",
      "storageSizeGB": 20,
      "description": "Test cluster 2"
    }
  • Status line – The first line of a response message is the status line. The status line contains a status code and a reason phrase.

  • HTTP response body – The response body is a JSON object that contains the requested information. For example, a GET request to get information about a cluster would return the nodeCount (number of Solr nodes) and nodeType (type of all Solr nodes), amongst other things. This is an example of an HTTP request body for getting information about a cluster:

    [
      {
        "id": "Test-2",
        "nodeCount": 2,
        "nodeType": "standard.small",
        "storageSizeGB": 20,
        "description": "Test cluster 2",
        "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-2/solr/",
        "status": "ready"
      }
    ]