Grades Checker And Notifier API*

"Disclaimer"

*The author of this script is not responsible for any damage caused by the use of this script. Use it at your own risk.

Sections

Problem statement

I am a student at the Faculty of Science, Alexandria University (AUFS). The university has a website where students can check their grades. However, the website is not very user-friendly, and it requires students to log in every time they want to check their grades. This is a problem for me because I often forget to check my grades. That's when I decided to create a script that will check my grades for me and notify me when they are available. I also wanted to make the script easy to use, so I decided to create a REST API that can be used by anyone who wants to check their grades.

Quick note: Make sure you are calling the API from a computer not using a mobile app because it does not work there. Use a tool like Postman as this tool is tested and it's working with it.

Screenshots

Login page: login page The login page of the website.

Main page: main webpage screen Once you log in, you will be redirected to the main page of the website. This page contains all the information about the student:

Grades page: grades page This is the page where the students can check their grades.

The page contains a table for each semester, with the info about the courses the student has enrolled into as shown in the image above. Please note that the website is in Arabic, and all the course names are in Arabic, I translated the site so anyone would understand the concept. So the API will send the grades in Arabic (as how you will see later) since the website is in Arabic by default..

Let me explain how to use the API

  1. You just need to call the /start endpoint with the following parameters:

    POST /start HTTP/1.1
{
    "username": "your_username",
    "phoneNumber": "your_phone_number", 
    "token": "your_token"
}
    • username (string): your username (the one you use to log in to the website, however, you can use anything as a username, it will be used to identify the user in the database)
    • phoneNumber (string): your phone number (the one you use to receive the notification). Make sure it is in valid WhatsApp phone number format.
    • token (string): I was lazy in the implementation of the API, so you will just need to log in to the website once and copy the token from the url. As this approach was the easiest for me to implement. (I will explain how to get the token in the next section)

Example call:

POST /start HTTP/1.1
   {
       "username": "2024123456",
       "phoneNumber": "+201234567890",
       "token": "your_token"
   }

Returns:

201 Created
    {
        "message": "Grade checking service started."
    }

To get the token, just follow these steps: 

https://www.scialex.org/S/your_token/Student/2018

"Hello! You have successfully registered to the grades checker API. You will be notified via SMS when your grades are available."
*Your username*: 'your_username'
*Your Pending Courses*: 'List of all pending courses'
*Your current CGPA*: 'your_current_cgpa'

The API will regularly check the grades every 9 minutes, and that was achieved by using cron-jobs, and if any grades had been revealed, it will send a message via SMS to the user with the revealed grades and the current CGPA. The message will look like this:

notification message Notification sent as an SMS message.

Sometimes, you would get a response like this:

500 Internal Server Error
    {
        "error": "Error starting background process for {username}: $ is not a function"
    }

I implemented the checking logic to check the Appreciation column, by default after you completed the course's survey, the grade for the course is 'P' indicating that the grade is not revealed yet. Once the grade is revealed, it will be changed to 'A' or 'B' or any other grade. So I just check if the grade is 'P' or not. If it is not 'P', then the grade is revealed and I will send a message to the user with the revealed grades and the current CGPA.

Once all grades are revealed, the API will stop checking the grades, delete all the user's data, and will send a message via WhatsApp to the user with a message like this:

"Hello! All your grades are revealed. Your current CGPA is {cgpa}. Thank you for using the grades checker API."

"Hello! Your token has expired. Please log in again and get a new token. Thank you for using the grades checker API."

However, if you decide to stop the service at anytime, you can just call the /stop endpoint with the following parameters:

DELETE /stop HTTP/1.1
    {
        "username": "your_username"
    }

Returns:

204 No Content
{
 "message": "Grade checking service stopped for user {username}."
}

"Hello! You have successfully stopped the grades checker API. Thank you for using the grades checker API."
Info:
*Duration*: x minutes
*Start date*: DD/MM/YYYY, HH/MM/SS (24-hour format)
*End date*: DD/MM/YYYY, HH/MM/SS (24-hour format)

Key Features

Additional Features

I implemented a rate limiting feature to prevent abuse of the API. The API will limit the number of requests to 100 requests every 15 minutes. If the user exceeds this limit, the API will return a 429 Too Many Requests error.

System Overview

Folders Component Diagram

UML Call Flow Diagram

Hosting

Well, I needed to host the API somewhere, so based on my use case, I decided to use Railway. The API is hosted on a free tier, as the API is not very heavy and does not require a lot of resources. But if the API is used by a lot of users, I would need to upgrade the plan, and I don't think I will do that. So the solution for you would be to either:

  1. Host it on your own server (if you have one).
  2. Use a free hosting service like Heroku, Railway or Render.
  3. Use a container service like Docker and host it on your own machine (which I highly recommend).
  4. Use a cloud service like AWS or Azure (which I don't recommend as it is expensive).

If you want to host it on your own server, you can just clone the repository using the following command:

git clone https://github.com/MohamedWElteir/grades-checker.git

Then, navigate to the project directory and install the dependencies:

npm install

Then, you can run the API using the following command:

npm start

Make sure you have the environment variables set up correctly. You can find the environment variables in the .env.example file. Just copy the file and rename it to .env, then fill in the required values.

Final words

In the end, this is a script I did for fun and because I am lazy and I don't want to check my grades every time. I am not responsible for any damage caused by the use of this script. Use it at your own risk. I hope you find it useful.

Contributing

If you have any new idea or suggestion that would add to the project, feel free to create a pull request with your additions!