Deploying an API to Heroku

Anyone that has met me knows that I love theme parks, that's why I recently deployed Parks, a platform to retrieve wait times at most Disneyland Park around the world.

To do so I implemented an unofficial API called themeparks by setting up endpoints on an Node server deployed to the free platform Heroku.

In this post I'll go through the steps necessary to have your own API up and running on that same platform; let's get started !

Step 1: Setting up your API

Node

First, create your project's repository and initialize it:

1mkdir my-awesome-api
2cd my-awesome-api
3npm init
4

Which will prompt you with some basic npm configuration questions, you can go through them by pressing enter, once asked entry point: (index.js), input server.js. That simply defines the entry point to our node program.
This process will create a package.json file, it holds metadata relevant to the project.

Heroku

Let's make sure you are logged in to Heroku's CLI, if you don't have it installed, you can do it here. Once installed run heroku login, which will prompt you for Heroku account information.

Once logged in, we can set up our project on Heroku by running heroku create, which will display:

1Creating app... done, ⬢ ancient-garden-55847
2https://ancient-garden-55847.herokuapp.com/ | https://git.heroku.com/ancient-garden-55847.git
3

Heroku sets up your application with a random (and rather soothing) name. Check out your Heroku dashboard, your project should be present.

We're all set up and ready to create some endpoints !

Step 2: The first endpoint

Let's start by installing the necessary packages like so:
npm install express body-parser

Create a server.js file with the following contents:

1const express = require("express"),
2  bodyParser = require("body-parser"),
3  app = express(),
4  port = process.env.PORT || 3000;
5
6app.use(bodyParser.json());
7
8app.get("/", (req, res) => {
9  res.send("Server works !");
10});
11
12app.listen(port);
13console.log("Server listening on port: " + port);
14

And navigate to localhost:3000 on your browser, you should see the following: Server works !.

Another example

That should be enough for you to get started on declaring your own endpoints, but I'll show a more elaborate example using the Themeparks API mentioned before.

First, I'll install the necessary package:
npm install themeparks

Then, I'll load the Themeparks module, set up options for my header and define a basic endpoint to retrieve every theme park the API handles (in the same server.js file):

1const Themeparks = require("themeparks");
2
3app.use(function (req, res, next) {
4  res.setHeader("Access-Control-Allow-Origin", "http://localhost:4200");
5  res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS, PUT");
6  res.setHeader(
7    "Access-Control-Allow-Headers",
8    "X-Requested-With,content-type"
9  );
10  res.setHeader("Access-Control-Allow-Credentials", true);
11  next();
12});
13
14app.get("/api/parks", (req, res) => {
15  let parks = [];
16  for (var park in Themeparks.Parks) {
17    console.log("* " + new Themeparks.Parks[park]().Name + " (" + park + ")");
18    parks.push(new Themeparks.Parks[park]().Name);
19  }
20  res.status(200).json(parks);
21});
22

I should now be able to target the /api/parks endpoint and have a list of parks displayed on my server's console.
To test it locally I can run my server and navigate to localhost:3000/api/parks which displays a long list of theme parks.

An application to this endpoint could be to return an array of Park objects to my client in order to inform the user of the supported parks.

Deploying it to Heroku

Deploying to Heroku is extremely easy:

1# Start by initializing your repository
2git init
3# Create a .gitignore file and ignore the node_modules folder
4echo "/node_modules" > .gitignore
5# Add and commit all of the other files
6git add .
7git commit -m "Initial commit"
8# Set up the remote to push to as the one created by Heroku
9# Replace ancient-garden-55847 by the name of your Heroku project
10heroku git:remote -a ancient-garden-55847
11# Push everything
12git push heroku master
13

Once pushed, Heroku will deploy your server in a matter of seconds, head to the Heroku dashboard and make sure your build has succeeded in the Latest activity panel.

You can now navigate to your API's URL (or click on Open app) and test it out in any browser !

In my case https://ancient-garden-55847.herokuapp.com/api/parks returns a list of parks !

Please note that Heroku's free version has your server sleep when not used for a certain period of time, so if it's the first time you're launching it it will probably take more time than usual.

Wrapping it up

We covered how to set up a very basic Node API from scratch and how to deploy it on the great platform that is Heroku. From here, you can build anything you want using the vast documentation that can be found anywhere on the web.

I hope that this post was helpful to some of you,

Happy coding,
@christo_kade