Skip to content

Latest commit

 

History

History
243 lines (194 loc) · 5.77 KB

Api_Documentation.md

File metadata and controls

243 lines (194 loc) · 5.77 KB

API Documentation for GradeTractor API

Base URL:
https://gradetractor.onrender.com

Authentication

Login

  • Endpoint: /api/v1/login

  • Method: POST

  • Description: Logs a user in and returns a JWT token for authentication.

  • Request Body (JSON):

    {
  "email": "[email protected]",
  "password": "your_password"
}

  • Response:

    • Success (200 OK): 
      {
  "success": "login successful",
  "token": {
    "access_token": "your_access_token",
    "refresh_token": "your_refresh_token"
  }
}
    • Error (400 Bad Request): 
      {
  "Error": "Email or password is incorrect"
}

Example cURL Request:

curl -X POST https://gradetractor.onrender.com/api/v1/login \
     -H "Content-Type: application/json" \
     -d '{"email": "[email protected]", "password": "your_password"}'

Register

  • Endpoint: /api/v1/reg

  • Method: POST

  • Description: Registers a new user and stores their email and password (hashed) in the database.

  • Request Body (JSON):

    {
  "email": "[email protected]",
  "password": "new_user_password"
}

  • Response:

    • Success (201 Created): 
      {
  "message": "Data inserted successfully",
  "inserted_id": "inserted_user_id"
}
    • Error (400 Bad Request): 
      {
  "Error": "Mail already exists"
}

Results Management

Upload Results Database

  • Endpoint: /api/v1/result

  • Method: POST

  • Description: Uploads the results database (a .xlsx file).

  • Request:

    • file: The results file (must be .xlsx format).

  • Response:

    • Success (200 OK): 
      {
  "message": "File uploaded successfully"
}
    • Error (400 Bad Request): 
      {
  "error": "Invalid file format. Please upload a file with the .xlsx extension."
}

Example cURL Request:

curl -X POST https://gradetractor.onrender.com/api/v1/result \
     -H "Authorization: Bearer <access_token>" \
     -F "file=@/path/to/result.xlsx"

Upload Template

  • Endpoint: /api/v1/template

  • Method: POST

  • Description: Uploads the template file (a .xlsx file) to generate the reports.

  • Request:

    • file: The template file (must be .xlsx format).

  • Response:

    • Success (200 OK): 
      {
  "message": "File uploaded successfully"
}
    • Error (400 Bad Request): 
      {
  "error": "Invalid file format. Please upload a file with the .xlsx extension."
}

Example cURL Request:

curl -X POST https://gradetractor.onrender.com/api/v1/template \
     -H "Authorization: Bearer <access_token>" \
     -F "file=@/path/to/template.xlsx"

Get All Classes

  • Endpoint: /api/v1/extractClasses

  • Method: GET

  • Description: Fetches all classes from the uploaded results file.

  • Response:

    • Success (200 OK): 
      {
  "allClasses": ["Class A", "Class B", "Class C"]
}
    • Error (404 Not Found): 
      {
  "error": "Results database not uploaded. Please upload the results file before proceeding."
}

Example cURL Request:

curl -X GET https://gradetractor.onrender.com/api/v1/extractClasses \
     -H "Authorization: Bearer <access_token>"

Generate Results

  • Endpoint: /api/v1/genresult

  • Method: POST

  • Description: Generates the individual results for a given class, including probation and termination lists.

  • Request Body (JSON):

    {
  "className": "Class A"
}

  • Response:

    • Success (200 OK): The response will be a zip file containing the generated individual reports for the selected class.

    • Error (400 Bad Request):

      {
  "error": "Results database not uploaded. Please upload the results file before proceeding."
}

    • Error (404 Not Found):

      {
  "error": "Class {className} not found. Please ensure the class exists in the uploaded results file."
}

Example cURL Request:

curl -X POST https://gradetractor.onrender.com/api/v1/genresult \
     -H "Authorization: Bearer <access_token>" \
     -H "Content-Type: application/json" \
     -d '{"className": "Class A"}'

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of a request. Below are some common error responses:

  • 400 Bad Request: The request could not be understood or was missing required parameters (e.g., missing file, invalid format).
  • 401 Unauthorized: Invalid or expired JWT token.
  • 404 Not Found: The requested resource was not found (e.g., missing class in the results).
  • 500 Internal Server Error: An error occurred on the server while processing the request.

JWT Authentication

For endpoints requiring JWT authentication (/api/v1/result, /api/v1/template, /api/v1/extractClasses, /api/v1/genresult), you must include the Authorization header with the Bearer <access_token>.

Example:

Authorization: Bearer <access_token>

The access_token can be obtained by logging in through the /api/v1/login endpoint.

Notes:

  • The Results Database and Template files should be in .xlsx format.
  • After uploading the results database and template, the system validates if both files are available before proceeding.
  • For Generating Results, you must specify the class name (from the available classes) to generate individual reports.
  • The generated reports include a list of students on probation or termination based on their performance.