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.
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
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.
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.
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:
- Execute any code.
- Make changes to the request and the response objects.
- End the request-response cycle.
- 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.
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.
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.
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.
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.
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.
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.