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:
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.
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).
|index||Add (or update) a document|
|get||Retrieve a specific existing document|
|delete||Delete a document|
|reindex||Copies a document from one index to another|
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.
|Search||Enter a search query and return hits matching the query|
|Count||See the number of matches for the query (can be executed across multiple indices and across one or more types.)|
|Validate||Validate a potentially heavy query without actually executing it|
|Explain||Calculate a score for a query for getting feedback on whether a document matches the query or not|
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.
|Index Management||Create a new Elasticsearch index|
|Delete an index|
|Close/open an index|
|Mapping Management||Add a new type to existing mapping|
|Retrieve mapping for a specific field|
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.
|Cat Indices||Gives us access to information and metrics regarding our indices|
|Cat Health||Provides an overview of the indices health|
|Cat Nodes||See information on your Elasticsearch nodes|
Tip: You can use headers to retrieve only relevant details on the nodes. Read here for more info.
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.
|Cluster Health||See an overview of the cluster health|
|Cluster State||See a detailed status report on your entire cluster. You can filter results by specifying parameters in the call URL.|
|Cluster Stats||See 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.
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.
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.
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.