The YRES Scheduler Backend API implements the core logic and functionality of the YRES Scheduler application. It serves as a RESTful API with which the YRES Frontend can communicate via HTTP requests in order to support the operation of the YRES scheduler.
- Ensure the latest version of Node.JS with NPM is installed. The site can be found here
- Clone the project repository with the following URL: (https://github.com/csc301-2023-fall/project-48-yorkregioneducationalservices-T.git)
- Navigate to the directory following directory in the project and install the dependencies using the command
npm install: (./deliverables/yres_scheduler/yres_scheduler_backend) - Finally, to start the backend API, use the command
node server.jswhile in the same directory as above.
We store a config file (./deliverables/yres_scheduler/yres_scheduler_backend/config), which contains particular information for running the application. In the config JSON file(s), we store information about the server (the port number it is hosted on), the database (including host address. If running the server locally, change “HOST” to “localhost”), authentication information, and additional constants (such as the singular campus id, and the number of students/counselors in a group).
We have a series of automated tests for entity creation stored in the project, which can be run while in the same directory as defined in the above setup section (./deliverables/yres_scheduler/yres_scheduler_backend), using the command npm test.
Additionally, we have set up a public testing workspace using Postman to test the various services our backend API should support. The workspace can be found here, where a window such as the one shown below should be seen:
To be able to run the tests, you must be in the “CSC301-group-48” Postman team (accessible in the top right) and have the environment set to “Local” (in the above screenshot, this is changed where it says “No Environment”). On the left sidebar, there are several tabs.
- The Collections tab contains tests for each service we have defined (these are folders of individual tests that perform one specific function).
- The Environments tab contains specific environment variables which we have defined to be used in our tests.
- The Flows tab contains several flowcharts corresponding to each of the services used by the application regularly, which run the tests defined in the Collections tab in the desired order to replicate the correct behaviour of the application.
To run the tests, the user must be logged in with a Postman account, and they should have the backend API running [locally] as described in the Setup section (i.e. using the command
node server.js).
NOTE: Tests cannot be run on the browser version of Postman without the Postman Desktop Agent Installed.
The services are meant to be tested using the flows. An image is provided below with an example of how the flow test:
The design of the YRES Scheduler Backend API aims to follow a hybrid CLEAN and service-oriented architecture, whereby guidelines are borrowed from both approaches. Use cases are placed into relevant groupings called services, typically corresponding to operations relating to an entity (e.g. the student service manages most operations directly related to the student entity). The platform is also divided into hierarchical layers of abstraction, each with specific responsibilities.
Backend API Higher-level Design Diagram
The innermost layer, Enterprise Business Rules, defines attributes and behaviour for all entities that are relevant to the scheduler application (e.g. activity, student etc). Entities are data structures that provide a common language for data to be manipulated across services and use cases. The Application Business Rules layer is where use case logic is implemented for corresponding API requests. Service modules export a functions for each API endpoint in their corresponding service. These modules throw informative service-specific errors and may call corresponding DB gateway plugins. Each service also has a corresponding DB gateway plugin, which implements operations related to querying and manipulating persistant storage, formatting the raw data into the relevant entities.
The Interface Adapters layer is where the unpacking of raw inputs (i.e. request body and query parameters) and preparation of response objects is handled. Controllers, which also act as presenters, call the corresponding service module function. Routers specify the routes, request contracts, and any custom middleware for each API endpoint and are responsible for calling the corresponding controller. Middleware, such as the Error Handler and Authentication Handler are inserted like intermediate layers between the routers and controllers.
The main components and structure of the YRES Scheduler Backend API package is mapped below:
API
-
Controllers
DB Gateway Plugins
Entities
Middleware
Routers:
The YRES Scheduler API utilises three means of testing:
-
Automated Unit Tests: Used to test the core logic of the entities using the Mocha testing framework. These can be found in the tests directory.
-
Postman Per-request Test Scripts: Used to test properties of request and response objects, validating the request body and status codes. These are implemented using Postman test scripts in our bespoke postman collection. These tests can be accessed from the Backend API Postman Collection.
-
Postman Flows Request-Chaining Tests: Used to test chaining multiple requests in a postman flow, verifying end-to-end functionality for specific services. These tests can be run manually and accessed from the Backend API Postman Collection.
The YRES Scheduler Backend API implements an informative and flexible error-handling system. The application defines a custom Express middleware for error handling. This ensures consistent formatting of error responses, setting custom status codes as appropriate and including relevant information about the error (e.g. the related service, a descriptive message etc). Each service has a corresponding custom error object which is contained within the Service Errors entity. Service errors should be thrown within service files by convention, although the error handling middleware will gracefully handle errors regardless of where they are thrown in the request-response flow of control.
Graceful Error Handling
Protected requests are authenticated using JWTs. All authentication-related requests are handled in the Account Service, including login, signup and for checking login status. A valid JWT is only granted if a login request is successful after passing valid login credentials.
{
"username": "admin",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MDIxNzk1NDgsImV4cCI6MTcwMjI2NTk0OH0.YyaCO9xF7pysuKb7ZDz9hcBaCRwk3e3C5_97oYe8j9Y"
}
Successful Login Response Example
The returned JWT (i.e. the token) must be added to the authorization header of all protected requests. If a token is not provided, or if the token is invalid or has expired, the request-response flow of control will be blocked by the custom Authentication Handler middleware. This ensures that sensitive user data is protected such that no information can be accessed or manipulated without authentication. If a request is blocked due to failed authentication, a 403 status code will be returned in the response.
The team followed JSDoc practices for documenting the code, which can be read here.
The team’s approach to designing the backend API employed a variation of clean architecture design (explained more in detail in the Architecture and Design section of this document), where each service begins its use case by receiving a request at its corresponding router file, sending the data down to the controller, which calls a function defined in the service file containing use case logic and may additionally call a database plugin to access/modify stored data. A response from the plugin is then passed back up along the chain and sent back to the front end of the project to be shown to the user.
Every type of request being handled follows the same architectural format with an entry in the router, controller, service and possibly database plugin files corresponding to the entities involved with the request. If a new type of request is to be supported, it would come with a new, parallel entry in the existing files for the entity being accessed, or within new files following the same design if the request does not fit in any of the existing paths. Additionally, any changes made to the back end of the project are checked for refactoring with the front end. A document detailing the front end of the project can be found here.