My first JavaScript project became a lesson in deploying a REST API json-server (and how you can do it, too.)

You know that moment when you realize the idea you had is going to be a lot a bit more work than you initially realized? Sometimes, your vision for something doesn't align with your skill-set, your tools, or your timeframe, or you just happen to dream big. And while that can be stressful, it can also be an amazing chance to grow.

I recently completed my first-ever JavaScript application. It's a simple web app that let's users explore the films and characters of Studio Ghibli. The project was my first assessment for FlatIron's Software Engineering Bootcamp and the requirements included using a public API with JSON as the communication format. The project is hosted here.

While I certainly learned a good amount about HTML, CSS, and JavaScript working on this project, a unique challenge presented itself during my workflow:

"How does a baby developer like me with essentially no back-end knowledge yet host her own REST API for a small project?"

Well, let me tell you.

The Problem

The general parameters for our project were:

A HTML/CSS/JS frontend app that accesses data from a public API. All interactions between the client and the API should be handled asynchronously and use JSON as the communication format.

I knew there was an existing Studio Ghibli API, but as I explored the data, I noticed that it didn't have any images, which didn't match my vision for my app. However, my instructor gave me the green light to use a locally hosted JSON-Server via this Node Module and I set off working on my project.

I built the shell of my site in HTML and CSS, then created a db.json file where I modified the Studio Ghibli API to hold images, descriptions, and other supplemental data I wanted to display.

Installing and running the JSON server locally took exactly two lines typed into the terminal:

$ npm install -g json-server

$ json-server --watch db.json

I then got my fetch() requests working using 'http://localhost:3000/...', wrote document.createElement about a hundred times, and was ecstatic with my final product.

Except, because I was using a locally hosted server, no one else could see my final product unless they cloned the repo and started a local server themselves. While this met the assessment requirements, I wasn't very happy with that as my end result.

I explored some free JSON hosting options, but I repeatedly hit walls with various feature limitations. Additionally, I encountered issues where the documentation for these options made significant assumptions of understanding or lacked documentation entirely, which is a problem for newbs like me.

A lesson for the future: your project is only as accessible as its documentation is clear.

The Solution

I reached out to my instructor again for advice on how I might be able to make my web app, well, an actual web app. She returned with this amazing template which allows developers to deploy the fake REST API JSON-server (which I was already using locally) to Heroku.

It works beautifully, and the directions are actually accessible for beginners. 🤯

All together, it took me about 15-minutes to get this working, including editing my fetch() requests to use my new API. Though, if you haven't already built your database (let's not talk about how much time I spent on that part of this project), your timeframe will certainly vary.

Here's how it works:

1. On the GitHub page for the template, select the 'Use this template' button

2. Name the repo and select 'Create repository from template'

3. Clone the repo to your local machine

4. Open the repo in your favorite text editor

5. Modify the contents of the db.json file to match your data

   • Check the documentation on structuring a JSON-server if you're unsure on how to format this

6. Sign up for Heroku

7. Install the Heroku CLI on your computer

   • This was the most intimidating part for me! Hang in there!

8. Run the heroku login command in your terminal and follow the prompts

9. cd into your local repo clone from step 3

10. While in your local repo, run the following:
    

     $ heroku create
     # A bunch of code will print
     $ git push heroku master
    

11. Run heroku open to see your JSON-server in all its glory

    

    • You can now fetch to your database using the Heroku App URL, and you have access to your REST API routes and endpoints. Hooray!

12. (optional) Heroku automatically 'sleeps' your app after 30 minutes of inactivity. It will reboot when a request is made but can take a few seconds. To avoid this, add your app to Kaffeine, which will ping your app every 30 minutes to prevent sleeping.

    • Heroku does require all free apps 'sleep' for 6 hours a day, but Kaffeine allows you to select your app's "bedtime." How sweet.

And with that, you can show your grandma that cool project you just finished without trying to talk her through installing Git.