API structure - IMS-IIITH/docs GitHub Wiki

  1. Authentication API (POST)
  2. User Details API (GET)
  3. Profile Details API (GET)
  4. Bank Details API (GET)
  5. Add Bank Details API (POST)
  6. Leave Request API (POST)
  7. Past Leave Applications API (GET)
  8. Courses List of Student (GET)
  9. Attendance (GET)
  10. Transcript (GET)

Authentication API

Endpoint: POST

Input (Form Data):

{
  "username": "[email protected]",
  "password": "student_password"
}

**Output **(JSON):

{
  "success": "Logged in Successfully",
  "headers": {
    "Set-Cookie":"access_token_ims_app"
  }
}

**Description: ** Upon successful verification, user is assigned with a cookie.

User Details API

Output (JSON):

{
  "success": true,
  "user": {
		"userType": Student,
   		"rollNumber": 2022111222,
		"name": "John Doe",
		"userID": "[email protected]"
  }
}

Description: The Authentication API is to verify user credentials. Upon a successful authentication request, the API returns detailed user information, including student details such as name, roll number, date of birth, academic information, contact details, and parent information. If unsuccessful then {“success”: false} JSON value. Note that the first field in “user”, namely, “userType” is an enum, which should contain The various types of users IMS allows, namely Student, Faculty, Staff. Currently, since we only know the student view of IMS, this API has fields of students only.

TODO: give authentication key as part of production API, which will be used in all other APIs to verify users.

Profile Details API

Format : https://domain/profile

Endpoint: GET

Output:

{
	"userType": Student,
	"general": {
		"rollNumber": 2022111222,
		"name": "John Doe",
		"userID": "[email protected]",
		"degree": "B.Tech",
		"department": "CSE",
		"specialisation": "No",
		"dateOfBirth": "1990-01-01",
		"gender": "Male",
		"aadhaarNumber": "123456789012",
		"category": "GEN",
		"admissionType": "JEE",
		"academicYear": "2022-2023",
		"mobile": "+919876543210",
		"email": "[email protected]",
		"fatherName": "John Doe Sr.",
		"motherName": "Jane Doe"
	},
	"address": {
		"street": "Downing Street",
		"location": "No. 10",
		"city": "New Delhi",
		"state": "DELHI",
		"country": "India",
		"zipCode": 201301
	}
}

Description: This API is a standalone GET API for profile details of the user. The “userType” attribute (enum) indicates whether the user is a student, faculty, staff etc. Currently, since we only know the student view of IMS, this API has fields of students only.

Get Bank Details

Endpoint: GET

Format : https://bank_details_api/user_email

Output (JSON):

    {
	"applicationStatus": "None”/”Applied”/”Approved”/”Rejected",
	"bankDetails": {
		"accountHolderName": "John Doe",
		"accountNumber": 9876543210,
		"bankName": "ABC Bank",
		"branchName": "Main Branch",
		"ifscCode": "QWERTY51656516",
		"bankAddress": "123 Main St, Cityville",
		"remarks": "Lorem ipsum dolor sit amet.",
"viewAttachment": "url",
	}
}

**Description: ** The Bank Details API, a GET request, includes a boolean flag, "hasBankDetails," indicating whether the user account has associated bank details. If true, the API provides essential information like the bank name, account holder name, account number, and branch details.

Add Bank Details API

Endpoint: POST

Input (JSON):

{
	“selectBank”: “SBI”,
 	"rollNumber”: 2022101005,
 	"accountHolderName": "John Doe",
		"accountNumber": “9876543210”,
		"bankName": "ABC Bank" || null,
		"branchName": "Main Branch" || null,
		"ifscCode": "QWERTY51656516" || null,
		"bankAddress": "123 Main St, Cityville" || null,
		"remarks": "Lorem ipsum dolor sit amet." || null,
"base64Data”: “base64_content_of_selected_file”
}

Output (JSON):

{
  "sent”: true,
  “Status”: “accepted/waiting/rejected”
}

Description:

The Add Bank Details API, accessed via a POST request, facilitates the submission of bank details including account information, branch details, and account holder's name for a specified roll number. The API responds with confirmation of successful submission and the current status of the request (accepted, waiting for approval, or rejected).

Leave Request API:

Endpoint: POST

Input (JSON):

{
  "rollNumber”: 2022101005,
  “fromDate”:  "08-03-2024",
  “toDate”: "19-03-2024",
  “totalDays”: 3,
  “reasonForLeave”:  enum("Sickness", "Family Emergency", "Technical Event", "Sports Event", "Cultural Event", "Any Other"),
  “leaveForOnlyPT/Sports”: enum(“Yes”, "No"),
  “justificationForLeave”: “Justification”,
  "patientCategory": enum("In Patient", "Out Patient") | null,
  "doctorCategory": enum("Institute Doctor", "Outside Doctor") | null,
  "eventType": enum("Conference", "Workshop") | null,
  "areYouPresentingAPaper": enum("Yes", "No" | null)
  "eventStartDate": "08-03-2024” | null,
  "eventEndDate": "09-03-2024" | null,
  "eventURL": "https://www.ieee-ras.org/conferences-workshops/fully-sponsored/icra" | null,
  “missedExamsForLeave”: enum(“Yes”, "No"),
  "semesterCourses": ["CS6.301-Design and Analysis of Software Systems", "CS7.302-Computer Graphics"],
  "typeOfExam": enum["Quiz", "Mid", "End Exam"] | null,
  "examCategory": enum("Theory", "Lab/Practical", "Both") | null,
  “remarks”: null | “Any Remark”, 
  “applicationDate”: "15-03-2024",
  "attachment1": “base64_encoded_data, 
"attachment2": “base64_encoded_data” | null

}

Output (JSON):

{
  "sentSuccessfully”: true,
  “Status”: “accepted/waiting/rejected”
}

Description:

The Leave Request API, accessible through a POST request, allows users to submit leave requests with details such as roll number, leave dates, reason, and supporting documents. The API responds with a status indicating whether the request was sent successfully and the current status of the leave application (accepted, waiting for approval, or rejected).

Note that optional dropdown fields (not marked with a red dot in the IMS form) have null as an acceptable value (same as we will pass null for optional fields where user does not enter anything).

Past Leave Applications API

Endpoint: GET

Format : https://course_list_api/user_email

Output (JSON):

{
  “Applications” : [	
{
	“LeaveID”: “2022113011_20230515”,
	“LeaveStatus”: “Applied”,
	“SubmitDate”: “2023-05-15”,
	“ReasonForLeave”: “enum("Sickness", "Family Emergency", "Technical Event", "Sports Event", "Cultural Event", "Any Other")”,
	“Justification”: “Justification”,
	“TotalDays”: “4”,
	“fromDate”: “23-02-2024”, 
	“toDate” : “25-02-2024”, 
	“missedExamsForLeave”: “YES”, 
	“Remarks”: Null,
  "semesterCourses": ["CS6.301-Design and Analysis of Software Systems", "CS7.302-Computer Graphics"],
  "typeOfExam": enum["Quiz", "Mid", "End Exam"] | null,
  "examCategory": enum("Theory", "Lab/Practical", "Both") | null,
		}
  ]
}

**Description: ** This API takes one input parameter user_email. This will give output the list of all the Leave Requests applied by a student along with the leave application status and some other parameters which were filled by the user during leave application form.

Courses List of Student

Endpoint: GET

Format : https://course_list_api/user_email

Output (JSON):

{
  "Courses": [
	{
  		"CourseCode": "CS1.301",
  		"CourseName": “Algorithm Analysis and Design",
		“Credits”: 4,
  		"Semester": "Monsoon",
  		"Year": “2023-24”,
  		"TotalClasses": 25,
  		"Attendance": {
    			"present": 23,
    			"absent": 2
  		},
		“Grade”: “A-”,
	},
	{
  		"CourseCode": "OC1.104",
  		"CourseName": "Sports 4",
		“Credits”: 1,
  		"Semester": "Monsoon",
  		"Year": “2022-23”,
  		"TotalClasses": 0,
  		"Attendance": {
    			"present": 0,
    			"absent": 0
  		},
		“Grade”: “A-”,
	},
  ]
}

**Description: ** This API for courses list is used in multiple places like Dashboard, Attendance and Transcript page. The list of courses are the ones which are only the ones taken up by the student so far (all semesters up to now) and appear on IMS. Each field contains information about courses such as number of Credits, Semester, Year, TotalClasses, Attendance (which further contains fields present and absent ) and Grade.

Attendance API

Endpoints: GET

Format: https://attendance_api/username=”[email protected]”&course_code=”CS1.301”

Output (JSON):

{
  “AttendanceReport” = [
	{ 
“Date”: “11-01-2024”, 
  	“Marked”: “P”
},
{ 
“Date”: “17-01-2024”, 
  	“Marked”: “P”
},
{ 
“Date”: “24-01-2024”, 
  	“Marked”: “A”
},
{ 
“Date”: “31-01-2024”, 
  	“Marked”: “P”
},
{ 
“Date”: “07-02-2024”, 
  	“Marked”: “P”
},
  ]
}

**Description: ** This API is for Attendance, which takes 2 parameters as input, the email and the course_id. This gives output an array of objects, each of these objects has two key value pairs. One key is Date with corresponding value as Date and other Pair key is the Marked and value is whether present or absent.

Transcript API

Endpoint: GET

Output (JSON):

{
    "Name": "John Doe",
    "Semesters": {
        "Monsoon2022": {
            "SGPA": 8.28,
            "CGPA": 8.28
        },
        "Spring2023": {
            "SGPA": 8.28,
            "CGPA": 8.28
        },
        "Monsoon2023": {
            "SGPA": 0,
            "CGPA": 8.28
        }
    }
}

Description: This API for the transcript will enable students to view their transcripts on their mobile phones with ease. The logical structure of the output JSON is to have a similar logical structure while rendering it in the app. Note that the last semester has null as the value for grades of each course. This indicates that the last semester is the current semester and thus does not have grades uploaded yet. This is the same as on the transcript page on the IMS website.