Run your first RESTful API service using docker

---

Written by - Millan Kaul

---

❓ Did you always wanted to run your API using docker 🐋

Run your own micro-service or REST API’s handling : GET
POST
PUT / PATCH
DELETE
i.e all CRUD operations.

❓❓ You always ran them locally, and wanted to run them inside a docker / dockrized with docker images

❓❓❓You wanted a service to run locally and for API testing , by hitting a API running (inside) a docker container

This article is 💯 for you.

In this article you will learn:

1. How to run a RESTful service locally using `docker` 🐋 
     1.1 Code available on GitHub 
2. How to create a - docker image from your code.
2. Verify abd list image created - docker image  
3. Running a docker image - docker run
4. How to start a running docker container - docker start
5. How to stop a running docker container - docker stop

🙌 And few tricks on the way we learn all of the above...

Lets call that dockrized microservice as node-app-http-docker

I will explain step by step how to achieve that, as well as share the complete source code.

Table of Contents

1. What is this project
2. Project setup
3. Running project using docker
   • Verify docker Image
4. Running docker Image
5. Testing (is it working)
6. STOPPING docker (running container)

What is this project❓

⚠️ NOTE: NOT SUITABLE FOR PRODUCTION USAGE

node-app-http-docker is a working project.

For getting started with a RESTful api server locally using docker

• It 🏃runs a server (docker) using nodejs [v18]
• Exposes following RESTful endpoints ( no database required) with all CRUD operations

Rest API call	CRUD operation	REST endpoints
GET	Read	http://0.0.0.0:8080/ http://0.0.0.0:8080/health http://0.0.0.0:8080/api/todos http://0.0.0.0:8080/api/todos/{id}
PATCH/PUT	Update	http://0.0.0.0:8080/api/todos/{id}
POST {with body}	Create	http://0.0.0.0:8080/api/todos
DELETE	Delete	http://0.0.0.0:8080/api/todos/{id}

You may get 3 types of response

Response Code	Response Status
200	OK
201	Created
404	Not Found

back to top

Project setup 💼

1. Prequisite Get docker [ I used version : v4.20.1]

   1.1 confirm by running dockdocker ps.

   if you are using it first time you will see this

    CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
   
   

1. Clone this repository

Using	Comand
via https	git clone https://github.com/eaccmk/node-app-http-docker.git && cd node-app-http-docker
via ssh	git clone git@github.com:eaccmk/node-app-http-docker.git && cd node-app-http-docker

back to top

Running the project using docker 🐋

It’s very simple and easy to start this service/application locally :

docker build . -t node-app-http-docker

⚠️ This may take a some time, if you are running this command first time or with slow internet connections speed.

Some interesting background why we use -t to Allocate a pseudo-TTY , read this stackoverflow thread

Verify docker Image

After docker build is completed, verify if a docker image is created and listed, run command docker images like :

docker images
REPOSITORY           TAG    IMAGE ID     CREATED       SIZE
node-app-http-docker latest ea23b8f98141 2 minutes ago 1.09GB

You may have more than one row in result, but make sure you have the one with REPOSITORY node-app-http-docker

also you may notice that a random (uniqie) IMAGE ID got assigned to your docker image, in my case it was ea23b8f98141

back to top

Running docker Image 🎽

Now that you have a IMAGE ID, lets run that image using docker run command like :

docker run -p 8080:8080 ea23b8f98141

Syntax: docker run -p <your-port-external>:<docker-internal-port-exposed-for-access> IMAGE_ID

For more details on -p read Publish or expose port (-p, –expose)🔗

❗ open a new tab on terminal and verify this docker (running)

docker ps

back to top

Testing (is it working ✅ ❎)

Lets hit the docker image as a client / User

Test Type (Positive /Negative)	CLIENT On terminal	Response	SERVER (if Docker running with logs)
✅ Home Page	curl http://0.0.0.0:8080	Welcome, this is your Home page	CalledGET : /
❎ Invalid endpoint	curl http://0.0.0.0:8080/dascbajb	{"message":"Route not found"}	CalledGET : /dascbajb This endpoint is not implemented / unavailable at the moment !!
✅ health check	curl http://0.0.0.0:8080/health	{"uptime":29.560686169, "message":"OK","timestamp":1644057630652}	CalledGET : /health

Some Screen shots from Postman

API	Screen
GET
POST
PATCH
DELETE

back to top

STOPPING docker (docker container) 🛑

First lets find the running one docker ps and then stop it using docker stop

CONTAINER ID  IMAGE        ....  .. . NAMES
06b6693e2e4a  ea23b8f98141 ....  .. . hardcore_black

# stop using CONTAINER ID
docker stop 06b6693e2e4a

# stop using image name
docker stop hardcore_black

In case you want to confirm —-» run again docker ps it should show no running image

docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES

Go back to top

That’s it !

Bookmark this blog : https://qualitywithmillan.github.io or follow me using #QualityWithMillan

This post was re-published on 2023-06-25 (Initiallly written on/before2022-01-01)