REST API ¶

The REST API is used by the user interface to communicate to your clusters. You may also communicate directly with the REST API, via http://localhost:5000/api

Table of Contents

Connection APIs ¶

Connections ¶

DELETE /api/clusters/(string: cluster_name)/_connect¶

DELETE /api/clusters/_connect¶

Deletes a connection from the connection pool and the database, by cluster name.

Note:	This method does NOT delete your Elasticsearch Cluster, just the connection from HQ to it.

Example request:

DELETE /clusters/_connect/<CLUSTER_NAME> HTTP/1.1
Accept: application/json

Parameters:	cluster_name (string) – Name of cluster connection to remove.
Returns:	List of active clusters.
Status Codes:	200 OK – Ok 400 Bad Request – bad request 500 Internal Server Error – server error

POST /api/clusters/(string: cluster_name)/_connect¶

POST /api/clusters/_connect¶

Creates a connection to a given host/port. Accepts a JSON POST BODY. This will add the connection, if it doesn’t already exist, to the pool of connections and save the details in the database.

Example request:

POST /api/clusters/_connect/ HTTP/1.1
Accept: application/json

{
    "ip": "127.0.0.1",
    "port": "9200",
    "use_ssl": false
}

Request Structure

(dict) –

ip (string) – IP address or host name

port (string) – ES REST API port

use_ssl (boolean) – Whether to use HTTPS or not.

Example response:

HTTP/1.1 201
Content-Type: application/json

{
  "data": [
    {
      "cluster_name": "",
      "cluster_ip": "",
      "cluster_port": "9200",
      "cluster_scheme": "http",
      "cluster_connected": true,
      "cluster_host": "http://10.0.0.0:9200",
      "cluster_version": "2.3.5"
    }
  ],
  "status_code": 200,
  "message": null,
  "response_time": 92
}

Response Structure

(dict) –

cluster_name (string) – cluster name

cluster_ip (string) – IP or host

cluster_port (string) –

cluster_scheme (string) –

cluster_connected (boolean) – Whether there was a successful connection.

cluster_host (string) – The complete connection url

cluster_version (string) – Elasticsearch version

Request Headers:
	Accept – application/json
Response Headers:
	Content-Type – application/json
Status Codes:	201 Created – connection created 400 Bad Request – bad request 500 Internal Server Error – server error

Cluster APIs ¶

Cluster List ¶

GET /api/clusters¶

Returns a collection of clusters.

Example request:

GET /api/clusters/ HTTP/1.1
Accept: application/json

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
    "status_code": 200,
    "response_time": 1648,
    "message": null,
    "data": [
        {
            "cluster_name": "",
            "cluster_ip": "",
            "cluster_port": "9200",
            "cluster_scheme": "http",
            "cluster_connected": true,
            "cluster_host": "http://10.0.0.0:9200",
            "cluster_version": "2.3.5",
            "cluster_health": {  }
        }
    ]
}

Response Structure

(dict) –

cluster_name (string) – cluster name

cluster_ip (string) – IP or host

cluster_port (string) –

cluster_scheme (string) –

cluster_connected (boolean) – Whether there was a successful connection.

cluster_host (string) – The complete connection url

cluster_version (string) – Elasticsearch version

Response Headers:
	Content-Type – application/json
Status Codes:	200 OK – OK 500 Internal Server Error – server error

Cluster Health ¶

GET /api/clusters/(string: cluster_name)/_health¶

Returns cluster health for one cluster

Example request:

GET /api/clusters/<cluster_name>/_health HTTP/1.1

Parameters:	cluster_name (string) – Name of cluster

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
    "status_code": 200,
    "data": [
        {
            "active_primary_shards": 10,
            "relocating_shards": 0,
            "cluster_name": "es_v2",
            "active_shards": 10,
            "task_max_waiting_in_queue_millis": 0,
            "number_of_pending_tasks": 0,
            "timed_out": false,
            "number_of_nodes": 1,
            "unassigned_shards": 10,
            "number_of_in_flight_fetch": 0,
            "initializing_shards": 0,
            "delayed_unassigned_shards": 0,
            "active_shards_percent_as_number": 50,
            "status": "yellow",
            "number_of_data_nodes": 1
        }
    ],
    "response_time": 38,
    "message": null
}

Response Headers:
	Content-Type – application/json
Status Codes:	200 OK – OK 500 Internal Server Error – server error

Cluster Summary ¶

GET /api/clusters/(string: cluster_name)/_summary¶

Given a cluster_name, returns summary information from several ES Cluster APIs.

Parameters:	cluster_name –
Return:

Cluster State ¶

GET /api/clusters/(string: cluster_name)/_state¶: Wrapper around https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-state.html

Node APIs ¶

Note that when calling the Node APIs, you can optionally pass in a comma-delimited list of node_id’s as parameters. Otherwise, information for all nodes in the cluster is returned.

Nodes Summary ¶

GET /api/nodes/(string: cluster_name)/(string: node_ids)/_summary¶

GET /api/nodes/(string: cluster_name)/_summary¶: Summary of Node(s). Returns a condensed view of all nodes in the cluster. Summary information is pulled from both the info and stats APIs.

Node Info ¶

GET /api/nodes/(string: cluster_name)/(string: node_ids)/_info¶

GET /api/nodes/(string: cluster_name)/_info¶: Wrapper for https://www.elastic.co/guide/en/elasticsearch/reference/master/cluster-nodes-info.html

Nodes Stats ¶

GET /api/nodes/(string: cluster_name)/(string: node_ids)/_stats¶

GET /api/nodes/(string: cluster_name)/_stats¶: Wrapper for https://www.elastic.co/guide/en/elasticsearch/reference/master/cluster-nodes-stats.html

Index APIs ¶

Indices ¶

POST /api/indices/(string: cluster_name)/(string: index_name)¶

POST /api/indices/(string: cluster_name)¶

Creates a new index on the cluster.

Parameters:	cluster_name – index_name –

Example request:

POST /api/indices/<cluster_name>/ HTTP/1.1
Accept: application/json

{
    "settings":
        {
            "number_of_replicas": 2,
            "number_of_shards": 4
        }
}

Request Structure

(dict) –

number_of_shards (string) –

number_of_replicas (string) –

Request Headers:
	Accept – application/json
Response Headers:
	Content-Type – application/json
Status Codes:	201 Created – index created 400 Bad Request – bad request 500 Internal Server Error – server error
Return:

GET /api/indices/(string: cluster_name)/(string: index_name)¶

GET /api/indices/(string: cluster_name)¶

Wrapper around https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-get-index.html

Parameters:	cluster_name – index_name –
Return:

Indices Summary ¶

GET /api/indices/(string: cluster_name)/(string: index_names)/_summary¶

GET /api/indices/(string: cluster_name)/_summary¶

Generate a summary view of one index for the UI.

Parameters:	cluster_name – index_names –
Return:

Index Stats ¶

GET /api/indices/(string: cluster_name)/(string: index_names)/_stats¶

GET /api/indices/(string: cluster_name)/_stats¶

Wrapper around https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-stats.html

Parameters:	cluster_name – index_names –
Return:

Index Command ¶

PUT /api/indices/(string: cluster_name)/(string: index_name)/action/(string: action)¶

PUT /api/indices/(string: cluster_name)/action/(string: action)¶

Trigger a command on one or many indices.

The possible commands are:

_open - Opens the Index for writes.
_close - Closed the index for writes.
_flush - Flushes caches
_refresh - Refresh the searchable data.
_force_merge - Formerly known as _optimize. Forces a segment merge.
_expunge_deleted - Forces deleted documents to be removed from disk.

Parameters:	cluster_name – action (string) – One of _open, _close, _flush, _refresh, _cache, _force_merge, _expunge_deleted index_name –
Return:

Index Shards ¶

GET /api/indices/(string: cluster_name)/(string: index_names)/_shards¶

GET /api/indices/(string: cluster_name)/_shards¶

Return shard information for this index.

Parameters:	cluster_name – index_names –
Return:

Index Alias ¶

DELETE /api/indices/(string: cluster_name)/(string: index_name)/(string: alias_name)/_aliases¶

DELETE /api/indices/(string: cluster_name)/(string: index_name)/_aliases¶

DELETE /api/indices/(string: cluster_name)/_aliases¶

Deletes an alias.

Parameters:	cluster_name – index_name – alias_name (string) – Alias to delete
Return:

POST /api/indices/(string: cluster_name)/(string: index_name)/(string: alias_name)/_aliases¶

POST /api/indices/(string: cluster_name)/(string: index_name)/_aliases¶

POST /api/indices/(string: cluster_name)/_aliases¶

Creates a new alias.

Parameters:	cluster_name – index_name – alias_name (string) –
Return:

GET /api/indices/(string: cluster_name)/(string: index_name)/(string: alias_name)/_aliases¶

GET /api/indices/(string: cluster_name)/(string: index_name)/_aliases¶

GET /api/indices/(string: cluster_name)/_aliases¶

Get all aliases for this index

Parameters:	cluster_name – index_name –
Return:

Index Mapping ¶

GET /api/indices/(string: cluster_name)/(string: index_name)/_mapping/(string: mapping_name)¶

GET /api/indices/(string: cluster_name)/(string: index_name)/_mapping¶

Returns one (or many) mappings that are found in the index.

Parameters:	cluster_name – index_name – mapping_name (string) – Mapping for only this doc type.
Return:

Reindex ¶

POST /api/indices/(string: cluster_name)/_reindex¶

Reindexes OR copies a mapping from a source to destination index.

Example request:

POST /api/clusters/_connect/ HTTP/1.1
Accept: application/json

{
    "settings": {
        "reindex_option" : "reindex",
        "source_index_name" : "SOURCE_INDEX",
        "destination_index_name" : "DESTINATION_INDEX"
    }
}

Request Structure

(dict) –

reindex_option (string) – Either “reindex” or “mapping_only”. This is taken as a command to trigger on action or the other.

source_index_name (string) – Index to copy from.

destination_index_name (string) – Destination index to copy to.

Example response:

HTTP/1.1 200
Content-Type: application/json

Request Headers:
	Accept – application/json
Response Headers:
	Content-Type – application/json
Parameters:	cluster_name –
Status Codes:	201 Created – connection created 400 Bad Request – bad request 500 Internal Server Error – server error

Diagnostics ¶

Cluster Diagnostics ¶

GET /api/clusters/(string: cluster_name)/diagnostics/_summary¶

Executes diagnostics rules across the cluster, and returns

Parameters:	cluster_name (string) –
Return:

Snapshots & Repositories ¶

Repositories ¶

GET /api/repositories/(string: cluster_name)¶

Lists all repositories found on the cluster.

Parameters:	cluster_name –
Return:

Snapshots ¶

GET /api/snapshots/(string: cluster_name)/repository/(string: repository_name)¶

Lists all snapshots found for this repository. WARNING: Returns a large payload if there are many snapshots and may even time out.

Parameters:	repository_name – cluster_name –
Return:

HQ APIs ¶

HQ Status ¶

GET /api/status¶

Returns status information about HQ and all connected clusters.

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
    "status_code": 200,
    "response_time": 1648,
    "message": null,
    "data": [
        {
            "name": "",
            "installed_version": "",
            "current_stable_version": "9200",
            "clusters": []
        }
    ]
}

Response Structure

(dict) –

name (string) –

installed_version (string) –

current_stable_version (string) – Taken from pinging github for the current master release version

clusters (list) –

Response Headers:
	Content-Type – application/json
Status Codes:	200 OK – OK 500 Internal Server Error – server error

HQ Routes ¶

GET /api/routes¶

From: http://flask.pocoo.org/snippets/117/

Returns a list of available routes in the API.

ES REST ¶

GET /api/rest/(string: cluster_name)/(string: command)¶

Endpoint for generic GET requests on a cluster. Simply does a pass-thru call to the actual cluster endpoint.

Response Headers:
Parameters:	cluster_name (string) – command (string) –
Returns:
	Content-Type – application/json
Status Codes:	200 OK – OK 500 Internal Server Error – server error

Table Of Contents