Let's take a break from Response Resources
and move to another section of our code, let's head back to our beloved router, today we're going to talk about Restful Routes
and how to implement them in our project.
Restful Api Concept
So, what is Restful Api
, you might heard that expression before, but what does it mean? Restful Api
is a concept that was introduced by Roy Fielding
in his dissertation, it's a set of rules that we should follow to create a Restful Api
, the main idea behind this concept is to make our api more standard
and consistent
, so that we can easily use it in any project.
Restful Api Rules
There are 6 rules that we should follow to create a Restful Api
, let's take a look at them:
-
Use nouns for the route path. For example,
/users
instead of/getAllUsers
. -
Use HTTP verbs for the route methods. For example,
GET
instead ofgetAllUsers
. -
Use plural nouns for the route path. For example,
/users
instead of/user
. -
Use query parameters to filter, sort, and paginate collections. For example,
/users?sort=age&limit=10
. -
Use HTTP status codes to represent the status of the response. For example,
200
for success,404
for not found, and500
for server error. -
Use snake_case (never camelCase) for query parameters and fields. For example,
/users?sort_by=age
.
I prefer camelCase in the last point though, but it's up to you.
Restful Api Routes
Now that we know the rules, let's take a look at the routes that we should implement in our project, we're going to implement the following routes:
-
GET /users
to get all users. -
GET /users/:id
to get a single user. -
POST /users
to create a new user. -
PUT /users/:id
to update a user. -
DELETE /users/:id
to delete a user. -
PATCH /users/:id
to update a user partially.
These are the main routes that we could implement in our restful API per module, but of course we can add any other routes that we need, for example, we can add a route to get the user's posts, or to get the user's comments, or to get the user's friends, etc.
Restful Api Implementation
We 're going to start our implementation starting from the next article, but this article we need to fix some stuff first as you will get hit with it if you are working with me step by step, inch by inch and code by code.
Response Body Parser
We have already introduced the Response Body Parser earlier to make any toJSON
called asynchronous, there are some issues with it, for example Is.iterable
will loop over strings
which is definitely not what we want, so we need to fix it, here is the new version of the Response Body Parser
:
// src/core/http/response.ts
// ...
/**
* Parse the given value
*/
protected async parse(value: any): Promise<any> {
// if it is a falsy value, return it
if (!value || Is.scalar(value)) return value;
// if it has a `toJSON` method, call it and await the result then return it
if (value.toJSON) {
return await value.toJSON();
}
// if it is iterable, an array or array-like object then parse each item
if (Is.iterable(value)) {
const values = Array.from(value);
return Promise.all(
values.map(async (item: any) => {
return await this.parse(item);
}),
);
}
// if not plain object, then return it
if (!Is.plainObject(value)) {
return value;
}
// loop over the object and check if the value and call `parse` on it
for (const key in value) {
const subValue = value[key];
value[key] = await this.parse(subValue);
}
return value;
}
What i added here is the Is.scalar
check, this checks if the value is string
, number
or boolean
, if so then just return it as we are not going to parse it.
I also enhanced the code in the promise all by splitting the Array.from
to be initialized in a variable, this is to make the code more readable.
Prevent sending response object to response
As the validator returns a response instance, any middleware also could return a response instance and the router handler of course could do so, then we need to check if the returned output is a response instance, then just return without sending it to the response.send
method, also to be more consistent, we could also add that check inside the send
method itself.
// src/core/http/response.ts
// ...
/**
* Send the response
*/
public async send(data?: any, statusCode?: number) {
// if the data is a response instance, then just return current response object
if (data === this) return this;
if (data) {
this.currentBody = data;
}
// parse the body and make sure it is transformed to sync data instead of async data
data = await this.parseBody();
if (statusCode) {
this.currentStatusCode = statusCode;
}
if (!this.currentStatusCode) {
this.currentStatusCode = 200;
}
// ...
}
Now let' update our request
execute method as well.
// src/core/http/request.ts
/**
* Execute the request
*/
public async execute() {
// check for middleware first
const middlewareOutput = await this.executeMiddleware();
if (middlewareOutput !== undefined) {
// 👇🏻 make sure first its not a response instance
if (middlewareOutput instanceof Response) return;
// 👇🏻 send the response
return this.response.send(middlewareOutput);
}
const handler = this.route.handler;
// 👇🏻 check for validation using validateAll helper function
const validationOutput = await validateAll(
handler.validation,
this,
this.response,
);
if (validationOutput !== undefined) {
// 👇🏻 make sure first its not a response instance
if (validationOutput instanceof Response) return;
// 👇🏻 send the response
return this.response.send(validationOutput);
}
// call executingAction event
this.trigger("executingAction", this.route);
const output = await handler(this, this.response);
// 👇🏻 make sure first its not a response instance
if (output instanceof Response) return;
// call executedAction event
this.trigger("executedAction", this.route);
// 👇🏻 send the response
await this.response.send(output);
}
Now we're good here. let's update another part of the response as well.
Not found response
We already have our notFound
method in the response class, but it is required to send a data to it, this is okay, but we can unify the response by making it optional, so we can call it without sending any data, here is the updated version of the notFound
method:
// src/core/http/response.ts
/**
* Send a not found response with status code 404
*/
public notFound(
data: any = {
error: "notFound",
},
) {
return this.send(data, 404);
}
// ...
Why would we do this? because later on, we can enhance it to make it configurable, so we can send a custom not found response, for example, we can send a custom not found json response.
This will apply to badRequest
method as well, but we'll keep it for now.
🎨 Conclusion
So in this article, we have talked about Restful APIs
and its standards, then we made some enhancements to our response
class to make it more consistent, and we also made some enhancements to our request
class to make it more consistent as well.
In our next chapter, we're going to start implementing our Restful API
and see how to handle it with our router system, stay tuned!
☕♨️ Buy me a Coffee ♨️☕
If you enjoy my articles and see it useful to you, you may buy me a coffee, it will help me to keep going and keep creating more content.
🚀 Project Repository
You can find the latest updates of this project on Github
😍 Join our community
Join our community on Discord to get help and support (Node Js 2023 Channel).
🎞️ Video Course (Arabic Voice)
If you want to learn this course in video format, you can find it on Youtube, the course is in Arabic language.
📚 Bonus Content 📚
You may have a look at these articles, it will definitely boost your knowledge and productivity.
General Topics
- Event Driven Architecture: A Practical Guide in Javascript
- Best Practices For Case Styles: Camel, Pascal, Snake, and Kebab Case In Node And Javascript
- After 6 years of practicing MongoDB, Here are my thoughts on MongoDB vs MySQL
Packages & Libraries
- Collections: Your ultimate Javascript Arrays Manager
- Supportive Is: an elegant utility to check types of values in JavaScript
- Localization: An agnostic i18n package to manage localization in your project
React Js Packages
Courses (Articles)
Top comments (0)