Create a Node.js function for an HTTP GET request for a Swagger API
This lesson will teach you how to create the javascript functions defined by the Swagger specification to return all Todo items to the client when requested with an HTTP GET method.
[00:01] The way the Swagger project is set up, we are going to write the code for our endpoints in this controllers folder. I'm going to create a different file for each endpoint, just to keep everything nice and separated.
[00:15] For example, if you remember back when we created our route end point, and for all of the others actually, I defined an ex-Swagger router controller and I defined an operation ID.
[00:30] Just like we set this up, whenever we turned on, when we built out the custom function for mock mode, we are going to use that same format for defining API endpoints in our controllers folders.
[00:41] I'm going to have a file named get all to-dos, which is where the router controller is going to look, and that's going to expose a function called get all to-dos that's going to fulfill the endpoint request.
[00:53] I'm going to create a new file here. Were going to call it just like we discussed, get all to-dos, and then, we are going to expose that function, and now, we will create that function. Let's do a little bit of housekeeping first.
[01:08] For my back end database, I'm going to use Elasticsearch. To do that, I need the Elasticsearch module installed in my project. I could do that with npm install, dash dash save, Elasticsearch. This just provides a little client that makes reading and writing to Elasticsearch a little bit easier.
[01:28] Back over in my code in my helpers folder, I'm going to create a new file called ES.JS. This is just going to contain the boilerplate stuff for our Elasticsearch. I'm going to declare an Elasticsearch and then require it, and then create a client using the Elasticsearch module.
[01:50] Inside of here, I'll define my host and it's running locally for me, it's going to be local host port 9200. I want my log level set to error.
[01:59] Now in my get all to-dos, I can declare my client using that helper that we created. In my function, for get all to-dos, I just want to grab all of the to-dos, right? I'm going to do that with client.search, which comes from the Elasticsearch client.
[02:20] Specify the index, and I'm storing everything in an index called to-do. And type is also going to be to-do. Elasticsearch, if you're not familiar with it, you can have different types within an index. I just named them both the same, again, is easier for me to remember.
[02:36] The query string that we want to pass is a star for everything. Elasticsearch is going to return a lot of data along with that that is related to the searching and indexing that I don't care about, I'm going to use a source include and specify that I want the to-do ID, the to-do completed tags, author, completed date and due date.
[03:06] That's going to have a callback that takes an error and a response object, and so here, it will have, if there is an error, we're going to send the error back to the client. Otherwise, we've got our results that are going to be coming back to us.
[03:25] Let's take a look and see what that looks like. If I open up a browser, I can search my local Elasticsearch instance and searching the to-do index, and you see all this information we get.
[03:37] Some information about the response itself, the number of shards, and primarily, what we're interested in is this hits object, which, inside the hits object is a hits array and then the items within that array are the individual responses from the Elasticsearch index.
[03:58] Each one of those has the index and type information and then the underscore source is really the information that we're looking to return to the client.
[04:09] We've got our data back from Elasticsearch and it's going to be in this format. We need to format it so it matches the schema definition that we promise to the client in our Swagger definition.
[04:20] To do that, I'm going to create a results array and then the results array is going to be equal to that response, the response we get back from the client. Then the hits object, and then the hits object inside the hits object, which was the array.
[04:38] We're going to do a map, and then, we'll map that with a function to hit that returns that underscore source object that we saw in the browser. Last thing I'll do is set the header so the client knows were passing application JSON and then we will send that results array back to the client.
[05:03] We coded up the get endpoint and we've got this really cool Swagger editor with this amazing "try this" operation button so you got to try it out, right?
[05:16] We'll scroll down here and we'll hit send request, because there's no parameters we get a response of success, and then in the rendered output here you can actually see the to-do items themselves as they are formatted from the API endpoint.
[05:31] You can also use the pretty output and look at the raw, at the pretty printed JSON or raw, which is just the straight beautiful text.
How do you have access to the es.js file functions if you are not exporting them? I'm getting:
{
"message": "client.search is not a function"
}
Thanks for posting! I'm creating a git repo that will setup Elasticsearch and the sample data for you. I'll have it uploaded and post it here in the next few hours.
Try this out and let me know if it helps: I updated the repo to include a docker container with Elasticsearch and a utility to import the sample data into Elasticsearch. Detail on usage can be found here: https://github.com/rekibnikufesin/nodejs-api-swagger/tree/master#running-elasticsearch-and-sample-data You'll need docker installed, but everything else should be included.
I am really glad you did this, but some film editing for would be also be beneficial.
Thanks for the feedback, Steve. Hearing what is done well and what could be improved helps me create better lessons over time. What editing is needed? Adding the installation steps to the lesson?
Ye, the ElasticSearch dep comes as a surprise.
In this video we're introduced to a new dependency which many of us don't have the means to evaluate without working out how to install, configure, and most likely debug to get running. What starts as a 5 minute video could end up being a 1+ hour effort in frustration for unfamiliar learners. With that said, thanks for the repo with the Docker container!
I'd evaluate how the lesson could be reduced to the most fundamental dependencies while still effectively demonstrating the intention of the lesson. Should the learner install MongoDb? There's a little bit of setup there, but there are more people familiar with Mongo than ElasticSearch. How about a json file? Zero setup sounds cool. Would a readFile be sufficient to demonstrate an asynchronous request to an endpoint? Does it benefit the learner to explain how to extract the data out of a deeply nested ElasticSearch's response object when a simpler object may do the same job?
I'm doing this course because I'm unfamiliar with Swagger, and want to learn how to use it to bolster my capabilities to build APIs - adding ElasticSearch makes me think "geez, I already don't know these other things, now there's a non-trivial search engine that I know even less about!"
This is a great series, but this lesson comes with a few surprises. I by no means want to diminish the hard work you've put into the course, just provide a perspective on what a noob may experience :)
I'm all but ready to give up. I was following along with the course fine up to this point, but then it all grinds to a halt:
At 02:00, the video jumps from the es.js file to another file, missing out the vital export line that makes it work.
At 03:26 I realise that I need an entire separate elasticsearch service installed and configured, with data loaded into it.
There are instructions in the comments here to get a docker container up and running to do that, but they don't currently work. (I've raised an issue.)
It would have been nice to have a Swagger tutorial that didn't require spending a load of effort setting up other technologies. I can't help but think that just reading some data from a flat file, or hardcoding a bit of data in the js files would have served to demonstrate Swagger just fine without requiring external services to be installed and configured. As is, it's hugely distracting from actually learning about Swagger.
If someone is receiving an "ERROR: manifest for elasticsearch:latest not found" In file: docker-compose.yml Line 4: image: elasticsearch:7.4.2 Line 14: image: kibana:7.4.2 https://hub.docker.com//elasticsearch https://hub.docker.com//kibana IDK if is a good idea change for the current versions or look forward the versions of the video I put the current version and I'm seeing stuff in the terminal
Hello changing docker-compose.yml line: 4: image: elasticsearch:5.6.16 line 14: image: kibana:5.6.16
Looks that at least Kibana is showing something in the browser after the docker-compose and visiting http://localhost:5601/
I have no idea how to test this episode because I do not have a database on my Elasticsearch installation. I'm running on OS X Sierra, but I do not know how to create an Elasticsearch DB or tables. Can you please guide me?