Purpose

The ES application programming interface (API) is a Representational State Transfer (REST) API for Enterprise Search. The api is installed under IIS. Client applications use REST methods like GET, POST, PUT and DELETE to access the api, for example to specify a search. The search is specified using json. The api performs the search on the Elastic Search cluster, and returns the search result to the application. The result is json. The api allows to build and run client applications on premise, whilst making use of Enterprise Search and the Elastic Search cluster elsewhere.

Security

Enterprise Search uses role-based access control (RBAC) to secure an Elastic Search cluster. A tenant (customer, application, company...) is authenticated using basic authentication: user name and password. The tenant is then authorized to access the tenant data only. Within the cluster a tenant demo will be able to access indexes demo-* only.

Communication between the api and the cluster is secure, over https.

Communication between client applications and the api also uses basic authentication, and is also made secure by means of https.

The api does not store credentials. It receives credentials from the client and it forwards these credentials to the cluster. It only maps user names to tenant names, in order to access the appropriate tenant indexes.

When adding a client application the owner of the api:

• Selects an available tenant name
• Configures roles and users for the cluster
• Adds user name - tenant name mappings to the api.

Index names

An endpoint may accepts zero, one or multiple index names, for example allowing to search multiple indexes.

POST _search/<index names>/_auto_complete
{
 "prefix": "bas"
}

<index names> is a comma separated list of index names, for example demo,test.

• Do not use spaces.
• Use lowercase index names.
• Index names correspond to silo codes in the Smartsite Manager.

Diagnostics

Invoking an endpoint results in a http status code and results in a json response body.

Status codes

• Status200OK
  • Success.
• Status400BadRequest
  • The json request body is not proper json.
  • Required properties are missing in the json.
• Status401Unauthorized
  • The basic authorization header is missing.
  • Authentication failed, for example because the password is wrong.
  • Attempt to access Elastic Search indexes for which there is no authorization.
• Status500InternalServerError
  • Errors in the configuration of the api.
  • An unanticipated exception occurred in the api.
• Status501NotImplemented
  • The api does not implement, for example, the parsing or presenting of a value of a particular datatype.

For the error cases there is still a json response body, containing information that may help diagnosing the issue.

• More details are included if the api is configured for development.
• Less details are included if the api is configured for production.

In both cases capture and inspect the return json if errors occur.

Whether the api runs in development or production is a Web.config / IIS setting:

<configuration>
  <location>
    <system.webServer>
      <aspNetCore>
        <environmentVariables>
          <!-- Development or Production. -->
          <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Production" />
        </environmentVariables>
      </aspNetCore>
    </system.webServer>
  </location>
</configuration>

Dry runs

For all endpoints it is possible to request a dry run by adding dry=true to the query string, for example

POST _search/<index names>/_search?dry=true
{
  "query": {
    ...
  }
}

The api will not perform the actual search, and will instead return json representing the request that would have been sent to Elastic Search, for example:

{
  "method": "POST",
  "path": "demo-news/_search",
  "body": {
    "query": {
      "bool": {
        "must": [
          {
            "terms": {
              ...
            }
          },
          {
            "bool": {
              "should": [
                {
                  "multi_match": {
                    "query": "wheather",
                    "type": "best_fields",
                    "fields": [
                      "doc_title^1",
                      "doc_body^1",
                      ...
                    ]
                  }
                }
              ]
            }
          }
        ]
      }
    },
    "from": "0",
    "size": "10",
    "sort": {
      "_score": "desc"
    },
    "_source": {
      "excludes": [
        "system_phrase_suggester",
        "system_autocomplete"
      ]
    },
    "aggs": {
      ...
    }
  }
}

 This is for development purposes.