JSON and REST — How You Talk to Elasticsearch
Elasticsearch has no special client language you must learn first. Every action — storing a book, searching for it, deleting a whole index — is an ordinary HTTP request carrying a JSON body. Once you can read one request, you can read them all.
The rule
Verb says what, path says where, JSON body says the details.
Throughout this course we run a small online bookshop. Its books live in an index called books, and one book looks like this:
{
"title": "The Quiet Garden",
"author": "Mira Das",
"genre": "fiction",
"price": 12.5,
"pages": 320,
"in_stock": true,
"published": "2019-04-02"
}That is JSON: curly braces hold an object of "key": value pairs. Values can be strings (in double quotes), numbers, true/false, null, arrays in [ ], or nested objects. Keys are always double-quoted strings, and there is no trailing comma after the last pair.
A request to Elasticsearch has three parts:
- The verb —
GETreads,PUTcreates or replaces at a path you name,POSTsends something for the server to act on (often with a server-chosen id),DELETEremoves. - The path — which resource:
/booksis the index,/books/_doc/1is the document with id 1,/books/_searchis the search endpoint of that index. Paths starting with_are Elasticsearch's own endpoints. - The body — JSON with the details, such as the document or the query.
GET /books/_search
{
"query": { "match": { "title": "garden" } }
}The reply is JSON too: a status code (200 OK, 201 Created, 404 Not Found, 400 Bad Request) plus a body you can read.
The shortcut
Read any request right to left in your head: first the body (what details?), then the path (on what?), then the verb (doing what?). Say it as one sentence.
Body
There is none. Nothing extra is needed to remove something.
The common trap is broken JSON: a missing quote around a key, a single-quoted string, or a trailing comma. Elasticsearch answers with a 400 and a parse error, and the fix is almost always in the punctuation.
Drills
Answer fast — trust the rule.
Which of these is valid JSON?
In GET /books/_doc/3, what does /books/_doc/3 tell Elasticsearch?
Which verb would you use to read a document without changing anything?
Elasticsearch answers a request with status 400 and a JSON parse error. What is the most likely cause?
Remember
- Verb says what, path says where, JSON body says the details.
- Read a request right to left and say it as one sentence.
- Double quotes on every key and string, no trailing commas.