This content originally appeared on DEV Community and was authored by Youssef Allali
Table Of Contents
- What is REST?
- Prerequisites
- Set up the workspace
- Set up the database
- Set up the routes
- Set up the controller
- Set up the server
- Test the API
- Conclusion
- Final words
What is REST?
REST is an acronym for Representational State Transfer and it is a software architectural style which uses a subset of HTTP
RESTful APIs relies on HTTP verbs to perform four operations :
The GET (to read a resource), POST (to create and/or update a resource), and DELETE (to delete a resource)
RESTful APIs are defined with the following aspects :
- A base URI, such as http://api.example.com/;
- Standard HTTP methods (e.g., GET, POST, PUT, and DELETE);
- Media types, such as application/json.
In this tutorial, we will learn how to create a RESTful API using Node.js.
Prerequisites
In order to follow along with this tutorial you will need
- A Node.js environnement installed on your machine;
- A text editor program or IDE (VS Code for example);
- A mongoDB instance (here in this tutorial, we will be using the cloud database MongoDB Atals).
- An API Client such as Postman to help us make HTTP requests and test our API server.
To avoid running into any compatibility issues, I will list the versions of programs and tools used in this tutorial :
| Tool | Version | How to check |
|---|---|---|
| Node.js | v14.16.1 | node -v |
| MongoDB Node.js driver | 3.6 or later | |
| express npm module | ^4.17.1 | npm list express |
| mongoose npm module | ^5.12.7 | npm list mongoose |
Set up the workspace
Start the project
In this tutorial, we will be creating a todo list application that will let us create, read, update and delete tasks.
Before we begin, make sure you have Node.js installed, mongoDB Atlas instance working and Postman ready for the testing.
Now, open a terminal window (or CMD, on Windows) in a preferred location or use the following command to create a folder and set it as a workspace:
$ mkdir ./todo-list-api
$ cd ./todo-list-api
Now, it's time to start our application by typing the following command:
$ npm init -y
What it basically does is create a file named package.json that contains all the information about our project and its dependencies.
the -y parameter lets me skip filling informations about my project since I could modify these later in the package.json file.
Create necessary folders and files
Now, let's create the file that will contain our server script, we'll be naming it index.js since that's the default name (other conventional names can be app.js or server.js).
In the command line, type the command that will create a new empty file:
$ touch ./index.js
Next, let's add some folders and files via the following commands:
Create a folder named "api" $ mkdir api
Create three separate folders "models", "routes", and "controllers" inside the "api" folder $ mkdir api/controllers api/models api/routes
Create the empty files "controller.js", "routes.js" and "model.js" inside their respective folders "controller", "routes", and "model" $ touch ./api/controllers/controller.js ./api/models/model.js ./api/routes/routes.js
Set up the database
Now that we have our server ready, let's set up a database.
- Install mongoose module
mongoose will be used to manage our MongoDB Atlas instance.
$ npm install mongoose --save
- Define a schema
Open the file "model.js" and type the following code and then save it.
// model.js
const mongoose = require('mongoose');
const taskSchema = new mongoose.Schema({
name: {
type: String,
required: 'Enter the name of the task'
},
date_created: {
type: Date,
default: Date.now
},
status: {
type: [{
type: String,
enum: ['pending', 'ongoing', 'completed']
}],
default: ['pending']
}
});
module.exports = mongoose.model('Tasks', taskSchema);
In the code above, we imported the mongoose module into our file and we created a model that defines the structure of our mongoDB collection.
Set up the routes
In Express, routing instructs the sever on how to respond to client request for a specific endpoint (URI) and a specific HTTP request method.
To do this, open the file "routes.js" and type the following code and then save it.
// routes.js
module.exports = (app) => {
const todoList = require('../controllers/controller.js');
app.route('/tasks')
.get(todoList.listTasks)
.post(todoList.createTask);
app.route('/tasks/:taskId')
.get(todoList.readTask)
.put(todoList.updateTask)
.delete(todoList.deleteTask);
};
In the code above, we defined two basic routes : "/tasks" and "/tasks/:taskId" with different methods; "/tasks" has the methods "GET" and "POST", while "/tasks/:taskId" has "GET", "PUT" and "DELETE".
As you can see, we also required the controller so each of the routes methods can call its respective handler function.
Set up the controller
open the file "controller.js" and type the following code and then save it.
// controller.js
const mongoose = require('mongoose');
const task = mongoose.model('Tasks');
exports.listTasks = (req, res) => {
task.find({}, (err, task) => {
if (err)
res.send(err);
res.json(task);
});
};
exports.createTask = (req, res) => {
const new_task = new task(req.body);
new_task.save((err, task) => {
if (err)
res.send(err);
res.json(task);
});
};
exports.readTask = (req, res) => {
task.findById(req.params.taskId, (err, task) => {
if (err)
res.send(err);
res.json(task);
});
};
exports.updateTask = (req, res) => {
task.findOneAndUpdate({_id: req.params.taskId}, req.body, {new: true}, (err, task) => {
if (err)
res.send(err);
res.json(task);
});
};
exports.deleteTask = (req, res) => {
task.remove({
_id: req.params.taskId
}, (err, task) => {
if (err)
res.send(err);
res.json({ message: 'Task deleted' });
});
};
In the code above, we defined 5 different functions for different actions:
-
listTaskslists our tasks; -
createTaskcreates a new task; -
readTaskreads the content of a task; -
updateTaskupdates the content of a task; -
deleteTaskdeletes a task.
Each of these functions is exported in order to be used in our routes.
Note that each of these functions uses different mongoose methods such as find, findById, save, findOneAndUpdate and deleteOne.
Set up the server
In this section, we will be connecting our controller.js, database, the created models, body parser and the routes together and at the end, we will run our server and test it.
- Install express module
Express will be used to create the server
$ npm install express --save
Open the file "index.js" and follow the steps.
Essentially, what we will be doing is
- Connect our database by adding a url to the mongoose instance connection (you can learn how to set up one by following this article);
- Load the created model - task;
- Register our created routes in the server.
Now, type the following code inside the file index.js and save it.
Note : Don't forget to replace the string in connectionUrl variable with your Atlas connection string.
// index.js
const express = require('express');
const app = express();
const port = process.env.PORT || 3000;
const mongoose = require('mongoose');
const task = require('./api/models/model.js');
app.use(express.json());
app.use(express.urlencoded({ extended: true }));
// mongoose instance connection url connection
mongoose.Promise = global.Promise;
// Replace the following with your Atlas connection string
const connectionUrl = "mongodb+srv://<username>:<password>@<clusterName>.mongodb.net/<databaseName>?retryWrites=true&w=majority";
mongoose.connect(connectionUrl, {
useNewUrlParser: true,
useFindAndModify: false,
useUnifiedTopology: true,
useCreateIndex: true
});
//import routes
const routes = require('./api/routes/routes.js');
//register the route
routes(app);
app.listen(port, ()=> {
console.log(`RESTful API server running on ${port}`);
});
Now, back to the terminal and type $ node ./index.js and if everything is fine, you'll see the message "RESTful API server running on 3000" printed to the console.
Test the API
Now that everything is connected, let’s test some of our routes with the the registered methods.
Launch Postman or use the web-based version (you'll need to set up an account, it's free).
In Postman, we will test our routes by making requests to their respective endpoints
Since there are no tasks nor tasklists in our database yet, get requests will return an empty array ([]) from the server. So the first thing we can do is create a task.
Create a task
In order to create a new task, let's make a POST request to the following http://localhost:3000/tasks
if you can't use Postman for some reason, you can always use the command line tool "curl".
$ curl --data-urlencode 'name=Do homework' http://localhost:3000/tasks
Delete a task
Now let's try to delete the task we have just created, in order to do that, let's make a DELETE request to the following http://localhost:3000/tasks/<taskId>
Note that we have to replace the :taskId placeholder with the task identified _id we received from the last request.
Again, if you can't use Postman, use the command line tool "curl".
$ curl -X DELETE "http://localhost/<taskId>"
Conclusion
Congrats! you made a functioning RESTful API
Final words
Don't hesitate to leave any questions you may have for me in the comments. I'll be pleased to reply and subscribe for more interesting content like this one.
This content originally appeared on DEV Community and was authored by Youssef Allali
Youssef Allali | Sciencx (2021-05-09T11:39:57+00:00) Build a simple Node.js RESTful API. Retrieved from https://www.scien.cx/2021/05/09/build-a-simple-node-js-restful-api/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.