Core API Reference

This document provides a comprehensive reference for the core API components of pyjiit. It covers the Webportal class (the main API client), WebportalSession (session management), and the overall structure of API interactions with the JIIT Webportal backend.

For detailed information on authentication and login flow, see Authentication Flow. For security and encryption details, see Security and Encryption. For specific data model structures, see the subsections under Data Models.

Overview

The core API is implemented in pyjiit/wrapper.py The primary entry point is the Webportal class, which provides methods for all JIIT Webportal operations. After authentication via student_login(), a WebportalSession object maintains the session state and authorization tokens for subsequent API calls.

Sources: pyjiit/wrapper.py1-489 pyjiit/__init__.py1-3

Core Class Hierarchy

Sources: pyjiit/wrapper.py1-489 pyjiit/__init__.py1-3

Webportal Class

The Webportal class at pyjiit/wrapper.py70-489 is the main API client. It manages the session lifecycle and provides methods for all webportal operations.

Initialization

# No parameters required
webportal = Webportal()

The constructor pyjiit/wrapper.py76-77 initializes with self.session = None. The session is populated after successful authentication via student_login().

Sources: pyjiit/wrapper.py70-77

Internal Request Handler: __hit()

The __hit() method at pyjiit/wrapper.py82-108 is the internal HTTP request handler used by all API methods. It centralizes:

Sources: pyjiit/wrapper.py82-108

Authentication Decorator

The @authenticated decorator at pyjiit/wrapper.py19-36 enforces session validation before method execution:

def authenticated(method):
    @wraps(method)
    def wrapper(self, *args, **kwargs):
        if self.session is None:
            raise NotLoggedIn
        return method(self, *args, **kwargs)
    return wrapper

All methods requiring authentication are decorated with @authenticated. If called without a valid session, they raise NotLoggedIn immediately.

Sources: pyjiit/wrapper.py19-36

WebportalSession Class

The WebportalSession class at pyjiit/wrapper.py38-68 encapsulates session state after successful login.

Session Attributes

get_headers() Method

The get_headers() method at pyjiit/wrapper.py61-68 generates HTTP headers required for authenticated requests:

{
    "Authorization": f"Bearer {self.token}",
    "LocalName": generate_local_name()
}

The LocalName header is regenerated for every request using the encryption module's generate_local_name() function.

Sources: pyjiit/wrapper.py38-68

API Method Catalog

The following table categorizes all public API methods by functionality:

Authentication Methods

Attendance Methods

Registration Methods

Exam Methods

Marks and Grades Methods

Fee Methods

Account Methods

Sources: pyjiit/wrapper.py111-488

API Endpoint Mapping

This diagram maps public API methods to their corresponding JIIT Webportal backend endpoints:

Sources: pyjiit/wrapper.py111-488

Request Payload Patterns

API methods use two payload patterns depending on the endpoint security requirements:

Pattern 1: Encrypted Payload (serialize_payload)

Used by methods requiring encryption, invoked via serialize_payload() from the encryption module:

Methods using encrypted payloads:

• student_login() wrapper.py128-137
• get_attendance() wrapper.py207
• get_registered_semesters() wrapper.py244
• get_registered_subjects_and_faculties() wrapper.py265
• get_semesters_for_exam_events() wrapper.py285
• get_exam_events() wrapper.py304
• get_exam_schedule() wrapper.py324
• get_semesters_for_marks() wrapper.py342
• get_semesters_for_grade_card() wrapper.py379
• get_grade_card() wrapper.py419
• get_sgpa_cgpa() wrapper.py436
• get_fines_msc_charges() wrapper.py454
• get_subject_choices() wrapper.py486

Pattern 2: Plain JSON Payload

Used by methods where the backend accepts unencrypted JSON:

Methods using plain JSON payloads:

• get_student_bank_info() wrapper.py164-168
• get_attendance_meta() wrapper.py180-186
• set_password() wrapper.py222-229
• get_fee_summary() wrapper.py466-469

Sources: pyjiit/wrapper.py111-488

Data Model Return Types

Other methods return raw dict objects containing API response data.

Sources: pyjiit/wrapper.py111-488 pyjiit/exam.py1-23 pyjiit/registration.py1-43

Exception Flow

Exception Types by Method

Sources: pyjiit/wrapper.py19-108

API Base URL

All API requests target the base URL defined at pyjiit/wrapper.py17:

API = "https://webportal.jiit.ac.in:6011/StudentPortalAPI"

Each method appends its specific endpoint path to this base URL. For example:

• get_attendance() → https://webportal.jiit.ac.in:6011/StudentPortalAPI/StudentClassAttendance/getstudentattendancedetail

Sources: pyjiit/wrapper.py17

Usage Summary

A typical API interaction flow:

1. Initialize: Create a Webportal() instance
2. Get Captcha: Call get_captcha() to retrieve a captcha challenge
3. Authenticate: Call student_login(username, password, captcha) to establish session
4. Query Data: Call authenticated methods like get_attendance(), get_exam_schedule(), etc.
5. Handle Errors: Catch NotLoggedIn, SessionExpired, LoginError, APIError as needed

For detailed usage examples, see Quick Start Guide.

Sources: pyjiit/wrapper.py70-489