Your first dead simple RESTful API with node.js and serverless

When it comes to trying to pick your first node.js project, there is no shortage of great ideas, in fact, there are entire GitHub repos dedicated to what your first project could be. Build a chatbot, No a weather API, what about a Pokedex?? It can be an overload to look at all of the possibilities right away.

In this tutorial, we’ll build a REST API that tells us about our users location!

Prerequisites:

• node
• serverless

Optional:

• Postman

Getting Started

The first thing we need to do is initialize our project, serverless comes with a large number of built-in templates, which makes it really easy to jump in and get started on our project, we’ll be using the aws-nodejs template which applies the default syntax for setting up Lambda cloud functions on Amazon Web Services, Super cool!

serverless create --template aws-nodejs --path location-finder

Great! So now we have some boilerplate code, let’s open it and get familiar with what that looks like.

You should see a file tree that looks like this

location-finder/

— handler.js

— serverless.yml

handler.js

One of the reasons that I think serverless makes such a good entry point for those creating their first API is just how simple everything is. For those who have ever interacted with an API this should seem pretty familiar, a good API should return at least a few things a statusCode, and a JSON body.

serverless.yml

Let’s talk about this file, this is where people who are new to serverless typically go glassy-eyed, especially if you’ve never seen a .yml file before, but rest assured it's nothing scary. In fact the whole point of YAML files is that they're intended to be human readable! Check out this link to learn more.

The first thing that we need to do to make our lives easier during local development is to install a serverless plugin called serverless-offline which we can do by adding this snippet.

plugins:
  - serverless-offline

You should add this to the file in a place that it makes sense and won’t get in the way later. I placed mine just under the service name.

Now that we have told the framework that we intend to use this plugin, we need to install it using npm. The first step to installing anything with npm is to set up our npm dependency

npm init -y

to skip all of the setup options. Then

npm install --save-dev serverless-offline

Say Hello!

Ok, the last thing we need to do to get our function talking to the outside world is to tell it how it should listen! Any good API has routes, and ours will too. In our serverless.yml file let's turn our attention to the functions section, this is where we'll define not only how the hello function that was created for us should be accessed, but also where we'll define all future functions, handlers, and events so it's important that you understand this especially.

functions

Inside of the functions block, we can describe what functions our server(less) should care about, hello is already described here, it's important to note that every function has a handler and every handler needs events if we expect to be able to interact with it from the outside world. In our example the only events we will be using are http but there are a large number of events available!

Heres our route so far

functions:
  hello:
    handler: handler.hello
    events:
      - http:
          path: say/hello
          method: get

It has

name: hello

handler: handler.js [hello function]

GET route: say/hello

We will be using this format as a template for future routes, see not too bad!

Start serverless in offline mode by typing

serverless offline

then, we can make our first request to

localhost:3000/say/hello

I use postman for testing, it’s easy to select the type of request you would like to make, and then see the result come back, but for GET requests you can also just use your web browser.

Getting The Users Location

Getting the location at this point is pretty trivial as long as we have the IP address of our user, let's look through the request from earlier and see if we can find it.

Sure enough, if we look at the event from our say/hello route, we see the users IP nested as event.requestContext.identity.sourceIp. Perfect!

After researching a few npm packages, I found iplocation, it’s accurate and the size is minimal compared to others making it a good choice for our application!

Install this package with npm like before

npm install --save iplocation

location.js

I created a new handler file called location.js, my file tree looks like this.

location-finder/

— handler.js

— location.js

— serverless.yml

Now, let’s stub out our handler function. It should look something like this.

Adding the code to make it work is also very minimal, we need to require("iplocation").default and pass the ip that we identified earlier.

Note: iplocation is async

final serverless.yml functions

Here is a quick reference to what my serverless.yml file looked like after creating this handler.

Wrap Up

Great, at this point you’ve created an extremely simple API that says hello, and also gets a users location based on their IP, let’s deploy this thing so you can see it really work! If you’ve gone through the steps to link your AWS account great, all you need to do is run

serverless deploy

if you haven’t linked your AWS account, or don’t have one let’s fix that! This example is designed for AWS Lambda, so you’re already halfway there!

Create an Account

Link AWS to serverless