Architecture & Design Of RESTful Service – Node.js API with TDD Tutorial

Now that we have gone through the requirements for API in the previous blog post, we can go ahead with defining the architecture of the customer information system.

Architecture – Customer Information System

This step is one of the essential steps before we begin the REST API development. Without clearly defining the architecture of the system we cannot build it without any issue. 

 The below image represents the system that we are building. Our system consists of a RESTful service and a database. The RESTful service, Customer Service, will be developed in Node.js with Express.js. MongoDB will be used as a database for the service to interact.

Architecture - Customer Information System
Architecture – Customer Information System

Low-Level Design

 So far we have defined the architecture for the customer information system. Now it’s the time to do a deep dive into the low-level design of the API. This step is the next one after the architecture.

In the low-level design, we will go to the API endpoint level design. After the request has been received by the RESTful service what will happen to service that request is what we will discuss in the low-level design of each of the API endpoints.

Usually, we will have to create the sequence diagram for each endpoint at this stage.

Before we jump onto the sequence diagrams it’s better to look at what are all the different components will be involved right from the request received stage until the response is sent back to the requester.

Layers Or Components Of Node.js REST API

Typically, RESTful service will accomplish the task of serving the request in the layered approach. In the Node.js world, there are different components available for us to implement the API functionality. They are route, middleware, service, and model.

Some of them may not be Node.js framework related layers, but they not new to the restful service world. In object-oriented languages, the services are most probably implemented in such a layered approach. We could borrow that approach here as well.

Below are the different components that we will be using to implement the Customer Service. Let’s have a brief look at these components and see what each will do.

1. Controller

 Usually, a controller will handle the request, invoke services to perform that action, and process response to sending back to the requester. Often controller will make a sequence of service calls in orchestration to accomplish the request as designed. Technically, it handles the flow of the middleware calls before it sends the response.

2. Middleware

 Middleware in a NodeJS world is a function that has access to the request object, response object, and next function. Here the next() function is used to invoke the next middleware in the stack. 

Middleware functions can perform the following tasks:

  1. Execute any code.
  2. Make changes to the request and the response objects.
  3. End the request-response cycle.
  4. Call the next middleware in the stack.

If the current middleware function does not end the request-response cycle, it must call next() to pass control to the next middleware function. Otherwise, the request will be left hanging.

3. Service

 A service is any function that can perform any task, like calculating some formula, accessing the database to read or write. Here we will use a service function to access the database for retrieving and storing the customer information. 

Also, the service will not have access to the request and response object. So anything needs to be done on the request and response object will have to be done in the controller only.

Then, the controller will have to pass that information as parameters to the service functions to perform the task. This way there is a clear segregation of duties among all the components in the RESTful service.

4. Model

 This component is the data access layer to fetch and save the documents. The service layer will be invoking the models to perform any actions on the document in the database via the model.

A model represents the document that can be created, updated, removed and fetched from the database.

REST API Sequence Diagrams

In the above sections, we have gone through all the components/layers we will be engaging to implement the RESTful service. The next step would be to see how can we use these layers to perform each of the functionalities that we defined in the requirements section. 

A sequence diagram would be a perfect tool to visualize and describe the flow of the process to develop the code. In this section, we will go through the sequence diagrams for each functionality.

This diagram will be very helpful during the development process as it sets the goal of what we are going to develop for those functionalities. With this clear end goal laid out, we can quickly and easily continue with the development and testing of the robust API.

1. Add Customer API – Sequence Diagram

 The below image shows the sequence diagram for the add new customer functionality. As you can see, the request comes to the controller; then it goes through the middleware; finally, it’s handled by the model to create the document in the database.

Add Customer API - Sequence Diagram
Add Customer API – Sequence Diagram

2. Get Customer List API – Sequence Diagram

The HTTP GET request will be sent to the controller to get the customers’ list. The request query parameters will be parsed to extract any searching, filtering and paging information within the controller.

Then the list of customers will be retrieved for the search, filter and paging query from the database via the service and model. Finally, the retrieved customer list will be sent back to the requester in the response object.

Get Customer List API - Sequence Diagram
Get Customer List API – Sequence Diagram

3. Get Customer API – Sequence Diagram

What we have here is the sequence diagram for the get a customer functionality. This flow starts with the request comes with the customer id to retrieve the information.

As in other sequences, the controller receives the request and retrieves the customer details through the service and model from the database.

Get Customer API – Sequence Diagram

4. Modify Customer API – Sequence Diagram

The sequence diagram for modifying customer functionality is shown here. As per this flow, the request comes with the changed customer details, and the controller handles it.

Before the controller responds with the modification result, it invokes the modifyCustomer function in the service. In turn, the model is getting called from the service to make the document update in the database.

5. Remove Customer API – Sequence Diagram

Just like the modify request, the delete a customer request comes with the customer id which needs to be removed from the database.

As usual, the controller initiates the process to delete the customer from the database with the help of service and model components.

Remove Customer API – Sequence Diagram

Next, you continue with the frameworks and tools needed for implementing the Customer Service API  functionalities.

Please check out the index page for this Node.js RESTful API development with TDD approach tutorial with all the posts in sequence in one place.

This blog post is an excerpt from the book Building Node.js REST API with TDD approach. Please check out the link for more information.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.