Elasticsearch API 101

One of the great things about Elasticsearch is its extensive REST API which allows you to integrate, manage and query the indexed data in countless different ways. Examples of using this API to integrate with Elasticsearch are abundant, spanning different companies and use cases.  

Documentation on the various API calls is extensive, and for some, this wealth of information can be somewhat daunting:  

Twitter

This article will try and provide an overview of the main API calls that you should get acquainted with as you get started with Elasticsearch, and will add some usage examples and corresponding cURL commands. The API examples detailed below are Document API, Search API, Indices API, cat API and Cluster API.  

This is by no means a full API guide — this would be impossible and is covered in Elastic’s official documentation. Advanced users might find this cheat sheet we put together helpful as it contains some useful tips and best practices on the Elasticsearch Cluster API. 

Document API 

This category of APIs are used for handling documents in Elasticsearch. Using these APIs, for example, you will create documents in an index, update them, move them to another index, or remove them.  

The APIs detailed below are for handling single documents, but you can also make use of certain multi-document APIs for performing bulk actions (e.g. multi get).   

CategoryDescriptioncURL
indexAdd (or update) a document
getRetrieve a specific existing document
deleteDelete a document
reindexCopies a document from one index to another

Search API 

As its name implies, these API calls can be used to query indexed data for specific information. Search APIs can be applied globally, across all available indices and types, or more specifically within an index. Responses will contain matches to the specific query.  

CategoryDescriptioncURL
SearchEnter a search query and return hits matching the query
CountSee the number of matches for the query (can be executed across multiple indices and across one or more types.)
ValidateValidate a potentially heavy query without actually executing it
ExplainCalculate a score for a query for getting feedback on whether a document matches the query or not

Indices API

This type of Elasticsearch API allows users to manage indices, mappings, and templates. For example, you can use this API to create or delete a new index, check if a specific index exists or not, and define new mapping for an index. 

CategoryDescriptioncURL
Index ManagementCreate a new Elasticsearch index
Delete an index
Close/open an index
Mapping ManagementAdd a new type to existing mapping
Retrieve mapping for a specific field

 cat API 

I personally love the cat API and use it whenever possible. The idea is to return data in a more user-friendly format as opposed to the normal JSON response. You can read about the various string parameters you can add to the cat commands here 

CategoryDescriptioncURL
Cat IndicesGives us access to information and metrics regarding our indices
Cat HealthProvides an overview of the indices health
Cat NodesSee information on your Elasticsearch nodes

Tip: You can use headers to retrieve only relevant details on the nodes. Read here for more info.

Cluster API 

These are cluster-specific API calls that allow you to manage and monitor your Elasticsearch cluster. Most of the APIs allow you to define which Elasticsearch node to call using either the internal node ID, its name or its address.   

For advanced usage of cluster APIs, read this blog post 

CategoryDescriptioncURL
Cluster HealthSee an overview of the cluster health
Cluster StateSee a detailed status report on your entire cluster. You can filter results by specifying parameters in the call URL.
Cluster StatsSee basic index metrics (e.g. number of shards) and information about your nodes (e.g.memory usage).

Ending with some tips 

It’s time to get your hands dirty! The best way to learn your way around these APIs is experimentation. There are plenty of resources which can help you with this, and a bunch of open source tools as well.  

First, read through the API conventions before you start here. These will help you learn about the different options that can be applied to the calls, how to construct the APIs and how to filter responses.  

I also recommend using the built-in console for playing around with the APIs — just enter your API in the editor on the left, and see the response from Elasticsearch on the right. 

Kibana

A good thing to remember is that some APIs change and get deprecated from version to version, and it’s a good best practice to keep tabs on breaking changes. 

Twitter API

The gradual removal of mapping types will affect the indexing and search APIs — you can see the effect of this change in the different versions here. 

The REST API is one of the main reasons why Elasticsearch, and the ELK stack as a whole, is so popular. The list above is merely the tip of the iceberg, but also a good reference point for getting started.  

Logz.io API 

Despite being a fully managed and hosted ELK solution, Logz.io provides a public API that is based on the Elasticsearch search API, albeit with some limitations. If you are using Logz.io, you can use this API to run search queries on the data you are shipping to your account. The query language used is Elasticsearch Search API DSL.

In addition, the Alerts API allows Logz.io users to create, delete and manage alerts. Again, there are some limitations that you should be aware of pertaining to the amount of concurrent APIs called.

Looking for an auto-scaling Elasticsearch service?