Meet my Free, Local API Server for your Front-End Adventures (written in Node.js)!

Hey, fellow Stackarians!

I hope that 2018 has been gracious to you so far, and you are ready for the upcoming challenges!

As this article is kinda long, let’s kick it off with a TLDR version:

I created a free API service you can run locally using Docker. This API service can be used as data source for your front-end project, since it has all the necessary basic functions needed to learn or experiment with different front-end frameworks.

Read the Documentation here!

Today, February 28, at 4 CET, we’ll host a live stream on Twitch, where Miklos Bertalan will use his private React stack to build a UI for the API server described in this post. It will be a start-from-scratch session, which features state management, routing, best practices and UX decisions. Follow us on Twitch to get a notification when we start!

Usage:

1. Install and start Docker
2. Download the pre-configured docker-compose file: docker-compose.yml
3. Open a new terminal tab and navigate to the folder where you downloaded the docker-compose file and run docker-compose up
4. Hit CTRL-C to stop the process and get back the command prompt
5. Run docker-compose down to remove the containers

Connecting to the database:

With these credentials, you can connect to the DB using your favorite client.
I can recommend Postico if you are on Mac, or DBeaver if you are looking for a multi-platform solution:

Default credentials:

user: root
password: root
host: localhost
port: 1330
database: api-db

The database is seeded with two different users with different privileges:

The pre-defined user with admin privileges:

username: admin,
email: admin@admin.com,
password: admin

The pre-defined regular user:

username: User Doe
email: user@user.com
password: 12345

You can reach the repo here
Freebie API server sourcecode

And here you may find the image on Docker Hub
Docker Hub image site

And now, if you are still with me, to full the story!

There are plenty of shiny toys to put your hands on this year if you would like to keep up the pace front-end-wise. React is still on the rocks, VueJs is right on its tail, and the good old Angular is getting better and better, so there are lots of opportunities to learn and experiment!

If backend programming is not your best side, or you just don’t want to waste time coding your own, here is a handy little thingy you can use: your very own local API server and database! (yaaaay!)

Sure, some great online services provide decent API servers, like Mockaroo, or you can just use your favorite service’s public API, like Spotify’s.

But – for me at least – they are just not scratching at the right spot. You know, I wanted something simple, but with all the most common things you can come by, like registering a new user, logging in, listing, adding and deleting stuff from a database. Just the usual CRUD operations.

I know, I know. First world problems.

So I decided to create my own super simple API server (emphasis on super simple), that can run locally. It has an attached database that I can browse with a UI database client app, pre-seeded, ready to go out of the box.

But then I thought: Hey, I cannot be the only one who needs this. Why don’t I make it public?

But then immediately:

‘But not everyone is comfortable with installing databases locally, not to mention the OS differences and yadda-yadda-yadda…’

Sure, these things are relatively easy, and anyone can do it with some documentation checking, but if you are not experienced with these kinds of things, it is just stealing your time from your primary goal: working on front-end. Why not make it simple then?

Probably you are now like,

‘Ok, Rob, this is some pretty long intro, we get it, you made something for yourself what is already out there, good work…’

BUT WHAT IS THIS AND WHERE IS THE LOOT?!

This is a simple backend service with a PostgreSQL database hooked up to it, seeded with some fake products data for a simple e-commerce site.

The server provides some features you can use through its API. You can:

• register a new user
• login and reach protected endpoints using JWT
• list fake products with enough details to create common product cards (with all-time favorites like Intelligent Frozen Chicken, Handcrafted Rubber Pizza not to mention the great Licensed Granite Salad! God, I love Faker!)
• search for a product by name or ingredient
• show one particular product
• edit a product
• delete a product

For further details, please see the documentation

The best part is that you don’t need to install PostgreSQL on your local machine, or add fake data (however you can)!

If you are reading this blog frequently, I’m sure you’ve already heard about Docker and containerization. If not, please let me summarize and (way over)simplify it for you:

Each container is a separate environment which is running on your machine, and you can reach it through a specific port, kinda like a virtual machine. This environment contains everything that is needed to run your code, and every time, on every platform, once it is created, it will be exactly the same as its image file declares it.

Why is this good for your health? Because I already made this image file and the one that runs the database in another container and links them together for you, and all you need to run it is Docker.

Dude, seriously… I won’t ask you twice…

I can imagine you’ve just shoveled a big chunk of coal to the rage train engine… But easy now, we are at the meat of it, finally!

This is what you need to do to run this backend service:

1. Install and run Docker

You find the instructions on the official site: Docker Install
With Docker, you will be able to run containers on your local machine without any environment setup hassle. Don’t forget to start it after installation, or your command line won’t recognize the docker command!

2. Grab this docker-compose file: docker-compose.yml

This file serves as a config file telling Docker which images you would like to have a copy of up and running. The image files are stored in Docker Hub. If it is not already on your machine, Docker will download it for you and cache it. So next time you wish to run it, it will be ready to use! Let’s take a closer look at it!

version: '3.3'
services:
  freebie-api-server:
    container_name: api-server
    image: robertczinege/freebie-api-server:latest
    ports:
      - '1337:1337'
    depends_on:
      - db
    environment:
      - DB_HOST=db
      - DB_PORT=5432
      - DB_USER=root
      - DB_PASSWORD=root
      - DB_DATABASE=api-db
      - PORT=1337
      - LOGGER_LEVEL=silly
      - TOKEN_SECRET='thisIsASuperSecretS3cr3t'
      - TOKEN_EXPIRATION=1h

  db:
    container_name: api-db
    image: postgres:10
    environment:
      - POSTGRES_USER=root
      - POSTGRES_PASSWORD=root
      - POSTGRES_DB=api-db
    ports:
      - '1330:5432'

This file tells Docker to set up two services, the ‘freebie-api-server’ called api-server and the ‘db’ called api-db. You will find them among the containers in Docker with these names after you started them.

The image property tells which image file should be used for this. As you can see, the service itself has its own image file available on my Docker Hub account, and the database is the official PostgreSql image file. If you don’t have them, Docker will download and save them.

There is an interesting line, the depends_on. This tells Docker to start the ‘db’ service (called api-db) first.

The ports is a really important property. The ports listed here will be exposed, so you can use them from the outside. In this case, the API service is available on the port 1337 and the database is available on port 1330 (the port 5432 is Postgres’ default port, which is exposed as 1330).

You can see a bunch of environmental variables. These environmental variables will be passed to the services running in the containers as you would pass them in through command line.

However, the DB_HOST env var is strange. It is not a URL or a connection string, as you would expect it to be. Well, Docker Compose will give this property automatically when started the ‘db’ service.

You can use these environment variables if you wish to deploy this service. But this is another whole story.

3. Navigate in the terminal to the directory where you saved the docker-compose file and run docker-compose up.

Docker Compose comes with Docker by default, and it really helps you to run multiple containers depending on each other.

This command will start both the server and the Postgres database linked to it. First, the server will fill the database with fake products and a default admin and regular user.

You will see the process of the startup in the command line. When you see the ‘Server is up!’ message, you know that everything is jolly good!

4. To stop the service, hit CTRL-C

CTRL-C will stop the processes, but will leave the containers up. You will get back your command prompt, so you can type in further commands.

If you run docker-compose down now, that will stop and remove both of the containers. When you start again with docker-compose up, the containers will be set up again with new random products.

5. You are good to go, and you can start developing your own frontend for it!

You can reach the service on localhost:1337/api. You can try this out using e.g. Postman, or just navigating to the localhost:1337/api/products URL in your browser. You will see the actual JSON response with the list of products.

Advanced, totally ethical pro tips:

• TIP 1: You can check if the service is up and running if you type in docker ps -a. This command lists all the running containers on your machine. If you see the api-server and the api-db in the list, you are good to go.
• TIP 2: You are able just to stop the containers but not removing them. In this case, the database will keep your changes and won’t be reseeded again. To achieve this, stop the containers like this:
  CTRL-C to exit the process and get back the command prompt
  docker stop api-server api-db to stop both of the containers
  docker start api-server api-db to start them again
• TIP 3: Connecting to the DB using database client

I recommend you to use Postico if you are on Mac or DBeaver if you are on Windows or Linux, but you can use it on Mac as well for exploring the database. They are free and very user-friendly.

You can connect to the database with the following credentials:

user: root
password: root
host: localhost
port: 1330
database: api-db

And boom, you are in. You can check and edit the data you find here. It is especially useful when you would like to add more users with admin privileges, since the database only comes with one predefined admin user to the service, or you can dump or restore the db. Well, for reasons.

Time to say goodbye!

So, this is it guys; I hope it was not so boring to read all those letters.

If you have any questions or feedback, please do not hesitate to drop them in the comments below, I much appreciate them! If you have any idea how I could improve it, that’s even better! I would love to hear them because this little project definitely could use some more love!

I hope you will find a good use for this thing as I already do!

See you later, alligator! 😉

And now, time for some self-advertisement!

If you are interested how to create a backend app like this, I recommend you our Beginner Node.js Training, where you can learn all the necessary knowledge to put together a service like this.

If you are more interested in the client side code and want to learn cool front-end frameworks, check out Angular and React trainings!