API Conventions in Elasticsearch
In the web, an API is a set of function calls to access software components in a particular application. For example, Facebook API allows the developers to access the data (like DOB or status update) or other functionalities from Facebook to create applications. Elasticsearch offers the REST API and it also uses some conventions that are discussed below in this chapter.
The Elasticsearch REST APIs are exposed through the JSON over HTTP. It uses the following conventions that are listed below in this chapter. These conventions can be applied throughout the REST API.
- Multiple Indices
- Date Math Support in Index Name
- URL based Access Control
- Common Options
Multiple Indices
In API, most of the operations like searching are for one or more indices. This helps the user to perform various operations (like searching) in multiple places through the entire API. The user can search all the available data by executing a search query for once.
For these queries, some notations are used, as given below:
- Comma Separated Notation (,)
- Wildcard Notation (*, +, -)
- URL Query String Parameter
- allow_no_indices
- _all keywords for all indices
These different notations are used to perform operations on multiple indices.
Date Math Support in Index Name
This API convention allows the user to search for a range of time-series indices. This type of search limits the range of number of indices that are being searched instead of searching all your time-series indices. This will reduce the load on a cluster and improve the execution performance.
- Almost all APIs support date math that contains an index
- Elasticsearch provides this convention to search the indices according to date and time.
- For which mathematical operation is used where we need to specify the date and time in a specific format to find the data for a particular date.
Expression: <static_name {date_math_expr {date_format|time_zone}}>
- static_name
- date_math_expr
- date_format
- time_zone
For example: <accountdetail – {now-2d { YYYY-MM-dd|utc }}>
- static_name is a part of expression that cannot be changed. It remains same in each date math index.
- date_math_expr contains the format of date (like dd-MM-YYYY) and time to be written in index. The default value is YYYY-MM-dd, which is changable.
- Let’s suppose today’s date is 18th May 2020, then it will return the account detail of 2020-05-16.
| Expression | Result |
|---|---|
| <accountdetail – {now-d}> | accountdetails – 2020-05-18 |
| <accountdetail – {now-2M}> | accountdetails – 2020-03-19 |
| <accountdetail – {now- {YYYY-MM}}> | accountdetails – 2020-05 |
URL-based Access Control
Many users use proxy with this convention for secure access to Elasticsearch indices.
Elasticsearch provides several API that allows the user to specify the individual request in request body such as multi_get, multi_search, and bulk requests, etc. The users have the choice to specify the index in URL, which makes URL-based Access Control more challenging.
Add the following setting in elasticsearch.yml file to disable the default action:
By default, it is set to true.
Common Options
Elasticsearch provides the following common options are:
- Pretty Result
- Human Readable Output
- Date Math
- Flat Settings
- No Value
- Time Unit
- Parameter
- Fuzziness
- Distance Unit
- Byte Size Units
- Unit-less quantities
- Enabling Stack Tracks
- Response Filtering
- Request Body in Query Setting
Now, we will discuss some common options in details:
Pretty Results
Append the following URL query parameter (pretty = true;) to get the result in a well-formatted JSON object.
Human Readable Output
Human Readable Output option is used to change the statistical response in either computer-readable form or human-readable form.
- If set human = false, it converts the statistical response to a computer-readable form.
- If set human = true, it converts the statistical response to a human-readable form.
The default value of it is FALSE.
For Example –