Original subtitles

So before we can talk about elastic search, we need to talk about rest and RESTful APIs,

the reason is that elastic search is built on top of a RESTful interface and that means to communicate

with elastic search,

you need to communicate with it through http requests that adhere to a rest interface.

So let's talk about what that means.

So let's talk about a http requests at a more high level here.

So whenever you request a web page from your browser what's going on is that your web browser is sending

an http request to a web server somewhere, requesting the contents of that web page that you want to

look at, and elastic search works the same way so instead of talking to a web server, you're talking to

an elastic search server

but it's the same exact protocol.

Now a http request contains a bunch of different stuff, more than you might think.

One is the method and that's basically the verb of the request,

what you're asking the server to do. So in the case of actually getting a web page back from a web server,

you'd be sending a get request saying that I want to get information back from the server,

I'm not going to change anything or any information on the server,

I just want to get information back from it.

You might also have a post verb that means that you want to either insert or replace data that's stored

on the server, or put which means to always create new data on the server or you can even send a delete

verb that means to remove information from the server. Normally, you wouldn't be doing that from a web browser

but from elastic search client,

totally a valid thing to do.

It also includes a protocol.

So specifically, what version of http are you sending this request in?

Might be http slash one point one, for example.

You will be sending that request to a specific host of course,

so if you're requesting a web page from our Web site that might be Sundog dash education dot com, and

the URL is basically what resource you are requesting from that server, what you want that server to

do.

So in the case, again, of a web server that might be the path to the web page that you want on that host.

There's also a request body you can send along, you don't normally see that with a web page request but

you can send extra data along in whatever structured data you want to the server within the body of

that request as well,

and finally, there are headers associated with each request that contain sort of metadata about the request

itself, for example information about the client itself,

that would be in the user region for a web browser,

what format the body is in that might be in the content type, stuff like that.

So let's look at a concrete example, again getting back to the example of a browser wanting to display

a Web site,

this is what a http request for that might contain.

In that example, we're sending a get verb to our web server and we're requesting the resource slash index

dot html from the server meaning we want to get the home page.

We will say that we are sending this in one point one http protocol, and we are sending it to a specific

host and that's our Web site sundog education dot com.

In this example, there is no body being sent across because all the information we need to fulfill this

request has already been specified and there'll be a whole slew of headers being sent along as well

that contains information about the browser itself,

what type of information and languages it can accept back in return from the server,

information about caching, cookies that might be associated with this site,

things like that.

So a bunch of information about you being sent around the internet whenever you request a web page,

but fortunately with elastic search, our use of headers is pretty minimal.

So with that, let's talk about a RESTful APIs, now that we understand http requests.

So the really pragmatic practical definition of a RESTful API is simply that you're using http requests

to communicate with your web service of some sort.

So because we're communicating with elastic search using http requests and responses, that means that

we're basically using a RESTful API.

Now there's more to it than that,

you know, we'll get to that.

But, at a very simple level, that's all it is,

you know, it sounds fancy but that's really it.

So for example, if I want to get information back from my elastic search cluster like search results

for example, I'm actually conducting a search,

I would send a get verb along with that request saying I want to get this information from elastic search.

If I want to insert information into it,

I would send a put request instead,

and the information that I'm inserting would be within the request body,

and if I want to actually remove information from my elastic search index, I would send a delete request

to get rid of it.

Malika said there's more to rest than that,

so let's get into the more the computer science the aspect of it.

Rest stands for a representational state transfer,

and it has six guiding constraints and well, to be honest, these aren't really constraints, not all of

them, some of them are a little bit fuzzy -

we'll talk about that.

Obviously, it needs to be a client server architecture we're dealing with.

You know, the concept of sending requests and responses from clients to servers doesn't really make sense

unless we're talking about client server architecture, and that is what elastic search offers.

We have an elastic search server or maybe even a whole cluster of servers and several clients that are

interacting with that server.

It must be stateless.

That means that every request and response must be self-contained,

you can't assume that there's any memory on the client or the server of the sequence of events that

have happened there really, so you have to make sure that all the information you need to fulfill a request

is contained within the request itself,

and you're not keeping track of state between different requests.

Casheability, this is more of a fuzzy one, it doesn't mean that your responses need to be cached on the

client,

it just means that the system allows for that.

So, maybe your responses include information about whether or not that information can be cached.

Again, not really requirement, but it's on this list of rest constraints. Layered system,

again, not a requirement, but it just means that when you talk to, for example, Sun Dog education dot com,

that doesn't mean you're talking to a specific individual server.

That request might get routed behind the scenes to one of an entire fleet of servers,

so you can't assume that your request is going to a specific physical host,

and again this is why statelessness is important because one host might not know what's going on in

the other necessarily, so they might not be talking to each other really.

Another sort of fuzzy constraint is code on demand,

and this just means that you have the capability of sending code across as a payload on your responses.

So for example, a server might send back javascript code as part of its response body that could then

inform the client how to actually process that data.

We're not actually going to be doing that with elastic search obviously, but rest says you can do that

if you want to.

And finally, it demands a uniform interface,

and what that means is a pretty long topic but, at a fundamental level it just means that your data that

you're sending along is of some structured nature that is predictable and, you know, you can deal with

changes to it in a structured way.

So, at a high level, that's all it is.

With that out of the way, why are we talking about rest at all here?

Well the reason is that we're going to do this whole course just talking about the http requests and

responses themselves, and by dealing with that very low level of how the RESTful API itself of elastic

search works, we can avoid getting mired into the details of how any specific language or system might

be interacting with elastic search. Pretty much any language out there,

Java, Javascript, Python, whatever you want to use is going to have some way of sending http requests,

so it really doesn't matter what language you're using.

What matters more, is understanding how to use elastic search, is how to construct these requests, and

how to interpret the responses that are coming back from it.

The mechanics of how you send that request and get the response back, is trivial,

right?

You know, any language can do that.

If you're a Java developer, you can go look up how to do that.

So we're not going to get mired in the details of how to write a Java client for elastic search,

instead what we're going to teach you in this course, is how to construct http requests and pass the responses

you get back from elastic search in a meaningful way,

and by doing that, you'll be able to transfer this knowledge to any language, in any system that you want,

very easily.

Some languages may have a dedicated client library for elastic search that provide sort of a higher

level wrapper over the actual http requests and responses, but they'll generally be a pretty thin wrapper

so you still need to understand what's going on under the hood, to use elastic serve successfully. A lot of

people get confused on that in this course,

but there's a very good reason for why we're just focusing on the actual http requests and responses,

and not the details of how to do it from a very specific language. All elastic search

documentation is done in the same style, the books that you can find about elastic search,

same idea,

there's a good reason for that. So, the way we're going to interact with elastic search in this course

is just using the curl command on a command line.

So again, instead of using any specific programming language or client library, we're just gonna use curl,

which is a Linux command for sending http requests right from the command line.

So we're just going to bash out curl commands to send out requests on the fly to our service and get the

responses back, and see what comes back from them.

The structure of a curl command looks like this.

Basically, it's curl

dash H, followed by any headers you need to send,

and for elastic search that will always be content type of application slash json, meaning that whatever

is in the body is going to be interpreted as json format,

it will always be that, and in fact we're gonna show you a little bit of a hack on how to always make

that header specified automatically for you on curl, to save you some typing.

That'll be followed by the URL, which contains both the host that you're saying this request to, and in

this course that will usually be the local host 127.0.0.1, followed by any information

that the server will need to actually fulfill that request.

So, you know, what index do I want to talk to, what data type, what sort of command am I asking it to do?

And finally, we will pass dash d, and then the actual message body within quotes that will be json formatted

data with additional information that the service needs to actually figure out what to give back to

you or what to insert into elastic search.

Let's look at some concrete examples to make that more real.

So the first one, at top here, were basically querying the Shakespeare index for the phrase 'to

be or not to be'.

So let's take a closer look at that curl command and what's in it.

Again, we're saying curl dash H content type application json, that's sending a http header that says that

the data in the body is going to be in json format. Dash X get, means that we're using the get method

or the get verb, depending on your terminology, meaning that we just want to retrieve information back

from elastic search, we're not asking you to change anything... and the URL, as you can see, includes

the host that we're talking to, in this case 127.0.01 which is the local loop back address where

your local host, elastic search runs on port ninety two hundred by default, followed by the index name

which is Shakespeare, and then followed by underscore search, meaning that we want to process

a search query as part of this request. The question mark pretty is a query line parameter, that means

that we want to get the results back in a nicely formatted human readable format, because we're gonna

be looking at it on the command line. And finally, we have the request body itself specified after a dash

D and between single quotes, and if you've never seen json before, this is what it looks like, it's just

a structured data format where each level is contained within curly brackets, so it's always contained

by curly brackets at the top level and then we're saying we have a query level, and within those brackets,

we're saying we have a match phrase command that matches the text entry 'to be or not to be'.

So that is how you would construct a real search query in elastic search, using nothing but a http request.

Another example here, we're going to be inserting data.

So in this one we're using a put verb. Again, to 127.0.0.1 on point ninety two hundred.

This time we're talking to an index called movies and a data type called movie, and it's using a unique

identifier for this new entry called 109487, and under movie I.D 109487 we're including

the following information in the message body.

The genre is actually a list of genres,

and in json that will be a comma delimited list of stuff that's enclosed in square brackets,

so this particular movie is both the IMAX and sci fi categories,

its title is Interstellar, and it came out in the year 2014.

So that's what some real http requests look like, when you're dealing with elastic search.

So now that you know what to expect and how we're actually going to use elastic search and communicate

with it, we can talk more about how elastic search works and what it's all about.

We'll do that next.