89-Nodejs Course 2023: Restful Routes: Introduction

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 of getAllUsers.
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, and 500 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

Packages & Libraries

React Js Packages

useFetcher: easiest way to fetch data in React Js

Courses (Articles)

Blog