timmapuramreddy/XP-I3068_API_DOCUMENTATION.md

XP-I3068: Enhanced Navigation APIs for TiQer Sessions - API Documentation

Overview

XP-I3068 implements enhanced navigation APIs for TiQer sessions with source tracking and Firebase synchronization, supporting both live TiQer sessions and individual quiz attempts across WebApp and Mobile platforms.

Authentication

All navigation endpoints require standard authentication:

Token Authentication: Authorization: Token <your_token_here>
Session Authentication: Django session cookies
Basic Authentication: HTTP Basic Auth

Base URL: /api/v2/contents/navigation/

Role-Based Access:

Teachers: Full access to all session navigation
Students: Access to sessions they're enrolled in
Admins: Full access to all navigation endpoints

Live TiQer Session Navigation APIs

1. Navigate to Next Question (Live Session)

Endpoint: POST /api/v2/contents/navigation/tiqer/{session_token}/next-question/ Purpose: Navigate to the next question in an active TiQer live session with Firebase synchronization Authentication: Required (Teacher/Student with session access) Frontend Critical: ⭐ YES - Essential for live session navigation

Path Parameters:

session_token (string): TiQer session identifier (e.g., "TQ_2024_89_ABC123")

Request Body:

{
    "source": "webapp",
    "kit_id": 45,
    "lesson_id": 123,
    "route": "recent",
    "navigation_context": {
        "current_position": 3,
        "user_initiated": true,
        "timestamp": "2024-07-29T10:45:30Z"
    }
}

Request Parameters:

source (string, required): Platform source ("webapp" or "mobile")
kit_id (integer, required): Kit identifier for content filtering
lesson_id (integer, optional): Lesson context for navigation
route (string, optional): Navigation route ("recent", "sequential", "adaptive")
navigation_context (object, optional): Additional navigation metadata

Database Mapping:

Updates TiQerSession.current_question and current_question_number
Creates entry in TiQerStateChangeHistory for navigation tracking
Triggers Firebase sync via TiQerFirebaseSync.update_session_navigation()
Filters questions from CustomActivityDetails with MCQ/TF types only

Success Response (200 OK):

{
    "status": "SUCCESS",
    "data": {
        "navigation_info": {
            "current_question_number": 4,
            "total_questions": 15,
            "has_next": true,
            "has_previous": true,
            "progress_percentage": 26.7,
            "navigation_path": "sequential"
        },
        "question_data": {
            "id": 1248,
            "content": "What is the pH of pure water at 25°C?",
            "question_type": "MCQ",
            "question_number": 4,
            "options": [
                {
                    "id": 4992,
                    "option": "6.0",
                    "option_letter": "A",
                    "is_correct": false
                },
                {
                    "id": 4993,
                    "option": "7.0",
                    "option_letter": "B",
                    "is_correct": true
                },
                {
                    "id": 4994,
                    "option": "8.0",
                    "option_letter": "C",
                    "is_correct": false
                },
                {
                    "id": 4995,
                    "option": "14.0",
                    "option_letter": "D",
                    "is_correct": false
                }
            ],
            "explanation": "Pure water at 25°C has a neutral pH of 7.0",
            "difficulty_level": "Medium",
            "time_limit": 30
        },
        "session_info": {
            "session_token": "TQ_2024_89_ABC123",
            "session_name": "Grade 8 Chemistry Quiz - Acids and Bases",
            "status": "Active",
            "teacher_name": "John Smith",
            "classroom_name": "Grade 8-A",
            "live_results_enabled": true
        },
        "firebase_sync": {
            "path": "/sessions/TQ_2024_89_ABC123/navigation",
            "sync_timestamp": "2024-07-29T10:45:32Z",
            "sync_status": "Success"
        },
        "source_tracking": {
            "navigation_source": "webapp",
            "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
            "ip_address": "192.168.1.105"
        }
    },
    "message": "Navigated to next question successfully"
}

Validation Rules:

Session must be in "Active" status
User must have access to the session (teacher or enrolled student)
Must have remaining questions in the sequence
Kit ID must be valid and accessible to user
Source must be "webapp" or "mobile"

Error Responses:

// 404 Not Found - Session not found
{
    "status": "FAILURE",
    "error_message": "TiQer session not found",
    "error_code": "SESSION_NOT_FOUND",
    "data": {
        "session_token": "TQ_2024_89_ABC123",
        "available_sessions": []
    }
}

// 400 Bad Request - End of questions
{
    "status": "FAILURE",
    "error_message": "No more questions available",
    "error_code": "END_OF_QUESTIONS",
    "data": {
        "current_question_number": 15,
        "total_questions": 15,
        "suggested_action": "End session or review questions"
    }
}

// 403 Forbidden - Access denied
{
    "status": "FAILURE",
    "error_message": "Access denied to this session",
    "error_code": "ACCESS_DENIED",
    "data": {
        "user_role": "Student",
        "session_classroom": "Grade 8-A",
        "user_classrooms": ["Grade 7-B"]
    }
}

2. Navigate to Previous Question (Live Session)

Endpoint: POST /api/v2/contents/navigation/tiqer/{session_token}/previous-question/ Purpose: Navigate to the previous question in an active TiQer live session Authentication: Required (Teacher/Student with session access) Frontend Critical: ⭐ YES - Essential for backward navigation

Path Parameters:

session_token (string): TiQer session identifier

Request Body:

{
    "source": "mobile",
    "kit_id": 45,
    "lesson_id": 123,
    "route": "recent"
}

Success Response (200 OK):

{
    "status": "SUCCESS",
    "data": {
        "navigation_info": {
            "current_question_number": 2,
            "total_questions": 15,
            "has_next": true,
            "has_previous": true,
            "progress_percentage": 13.3,
            "navigation_path": "sequential"
        },
        "question_data": {
            "id": 1246,
            "content": "Which of the following indicators turns red in acidic solution?",
            "question_type": "MCQ",
            "question_number": 2,
            "options": [
                {
                    "id": 4988,
                    "option": "Litmus paper",
                    "option_letter": "A",
                    "is_correct": true
                },
                {
                    "id": 4989,
                    "option": "Phenolphthalein",
                    "option_letter": "B",
                    "is_correct": false
                }
            ]
        },
        "session_info": {
            "session_token": "TQ_2024_89_ABC123",
            "session_name": "Grade 8 Chemistry Quiz - Acids and Bases",
            "status": "Active"
        },
        "firebase_sync": {
            "sync_status": "Success",
            "sync_timestamp": "2024-07-29T10:44:15Z"
        }
    },
    "message": "Navigated to previous question successfully"
}

Error Response:

// 400 Bad Request - Beginning of questions
{
    "status": "FAILURE",
    "error_message": "Already at the first question",
    "error_code": "BEGINNING_OF_QUESTIONS",
    "data": {
        "current_question_number": 1,
        "total_questions": 15
    }
}

3. Get Current Session State

Endpoint: GET /api/v2/contents/navigation/tiqer/{session_token}/current-state/ Purpose: Retrieve current session state and question information for synchronization Authentication: Required (Teacher/Student with session access) Frontend Critical: ⭐ YES - Essential for session synchronization

Path Parameters:

session_token (string): TiQer session identifier

Query Parameters:

kit_id (integer, required): Kit identifier for content context
lesson_id (integer, optional): Lesson context
route (string, optional): Navigation route preference
include_analytics (boolean, optional): Include real-time analytics data

Success Response (200 OK):

{
    "status": "SUCCESS",
    "data": {
        "session_state": {
            "session_token": "TQ_2024_89_ABC123",
            "session_name": "Grade 8 Chemistry Quiz - Acids and Bases",
            "status": "Active",
            "start_time": "2024-07-29T10:35:00Z",
            "current_question_number": 3,
            "total_questions": 15,
            "progress_percentage": 20.0
        },
        "current_question": {
            "id": 1247,
            "content": "Which of the following is a strong acid?",
            "question_type": "MCQ",
            "question_number": 3,
            "options": [
                {
                    "id": 4990,
                    "option": "HCl",
                    "option_letter": "A",
                    "is_correct": true
                },
                {
                    "id": 4991,
                    "option": "CH₃COOH",
                    "option_letter": "B",
                    "is_correct": false
                }
            ],
            "time_limit": 30
        },
        "navigation_context": {
            "has_next": true,
            "has_previous": true,
            "can_navigate": true,
            "navigation_locked": false
        },
        "user_context": {
            "user_role": "Student",
            "responses_submitted": 2,
            "current_score": 20,
            "participation_status": "Active"
        },
        "firebase_sync": {
            "last_sync": "2024-07-29T10:43:45Z",
            "sync_status": "Connected",
            "real_time_updates": true
        },
        "analytics": {
            "total_responses": 24,
            "response_rate": 85.7,
            "average_response_time": 18.5
        }
    },
    "message": "Current session state retrieved successfully"
}

Database Queries:

Retrieves TiQerSession with related teacher, classroom, and assignment data
Gets current question from CustomActivityDetails
Fetches user responses from CustomActivityAnswers
Queries TiQerDeviceSync for connection status

Individual Quiz Navigation APIs

4. Navigate to Next Question (Individual Quiz)

Endpoint: POST /api/v2/contents/navigation/individual/next-question/ Purpose: Navigate to next question in individual quiz attempt (non-live session) Authentication: Required (Student) Frontend Critical: ⭐ YES - Essential for individual study sessions

Request Body:

{
    "activity_id": 234,
    "kit_id": 45,
    "current_position": 3,
    "source": "webapp",
    "lesson_id": 123,
    "route": "sequential",
    "user_context": {
        "study_mode": "practice",
        "time_tracking": true,
        "show_explanations": true
    }
}

Request Parameters:

activity_id (integer, required): Activity/assignment identifier
kit_id (integer, required): Kit identifier for content filtering
current_position (integer, required): Current question position (0-based)
source (string, required): Platform source ("webapp" or "mobile")
lesson_id (integer, optional): Lesson context
route (string, optional): Navigation route preference
user_context (object, optional): Individual study preferences

Database Mapping:

Queries Assignments table for activity details
Filters CustomActivityDetails for MCQ/TF questions only
Creates or updates CustomActivityAnswersHeader for session tracking
No Firebase sync (individual sessions don't require real-time updates)

Success Response (200 OK):

{
    "status": "SUCCESS",
    "data": {
        "navigation_info": {
            "current_position": 4,
            "total_questions": 20,
            "has_next": true,
            "has_previous": true,
            "progress_percentage": 20.0,
            "navigation_mode": "individual_study"
        },
        "question_data": {
            "id": 1258,
            "content": "What happens when an acid reacts with a base?",
            "question_type": "MCQ",
            "position": 4,
            "options": [
                {
                    "id": 5002,
                    "option": "Neutralization occurs",
                    "option_letter": "A",
                    "is_correct": true
                },
                {
                    "id": 5003,
                    "option": "Explosion occurs",
                    "option_letter": "B",
                    "is_correct": false
                }
            ],
            "explanation": "When an acid reacts with a base, neutralization occurs, producing salt and water",
            "difficulty_level": "Easy",
            "learning_objective": "Understand acid-base reactions"
        },
        "activity_context": {
            "activity_id": 234,
            "activity_name": "Chemistry Fundamentals - Individual Practice",
            "kit_name": "Chemistry Kit - Acids and Bases",
            "estimated_time": "25 minutes"
        },
        "study_features": {
            "explanations_available": true,
            "hints_available": true,
            "time_tracking": true,
            "bookmarking": true
        }
    },
    "message": "Navigated to next question in individual quiz"
}

Validation Rules:

Activity must be accessible to the user
Current position must be within valid range
Kit must be associated with the activity
User must have appropriate permissions for the activity

5. Navigate to Previous Question (Individual Quiz)

Endpoint: POST /api/v2/contents/navigation/individual/previous-question/ Purpose: Navigate to previous question in individual quiz attempt Authentication: Required (Student) Frontend Critical: ⭐ YES - Essential for review and correction

Request Body:

{
    "activity_id": 234,
    "kit_id": 45,
    "current_position": 4,
    "source": "mobile",
    "lesson_id": 123,
    "review_mode": true
}

Success Response (200 OK):

{
    "status": "SUCCESS",
    "data": {
        "navigation_info": {
            "current_position": 3,
            "total_questions": 20,
            "has_next": true,
            "has_previous": true,
            "progress_percentage": 15.0
        },
        "question_data": {
            "id": 1257,
            "content": "Which pH range indicates an acidic solution?",
            "question_type": "MCQ",
            "position": 3,
            "options": [
                {
                    "id": 5000,
                    "option": "0 to 6.9",
                    "option_letter": "A",
                    "is_correct": true
                },
                {
                    "id": 5001,
                    "option": "7 to 14",
                    "option_letter": "B",
                    "is_correct": false
                }
            ]
        },
        "user_response": {
            "previously_answered": true,
            "selected_option": "A",
            "is_correct": true,
            "submitted_at": "2024-07-29T10:42:15Z",
            "response_time_seconds": 15.2
        }
    },
    "message": "Navigated to previous question"
}

Navigation Response Format

Standard Navigation Response Structure:

{
    "status": "SUCCESS|FAILURE",
    "data": {
        "navigation_info": {
            "current_question_number": "integer",
            "current_position": "integer", 
            "total_questions": "integer",
            "has_next": "boolean",
            "has_previous": "boolean",
            "progress_percentage": "float",
            "navigation_path": "string"
        },
        "question_data": {
            "id": "integer",
            "content": "string",
            "question_type": "MCQ|TF",
            "options": [
                {
                    "id": "integer",
                    "option": "string",
                    "option_letter": "A|B|C|D",
                    "is_correct": "boolean"
                }
            ],
            "explanation": "string",
            "difficulty_level": "Easy|Medium|Hard"
        },
        "session_info": "object (for live sessions)",
        "activity_context": "object (for individual quizzes)",
        "firebase_sync": "object (for live sessions only)"
    },
    "message": "string"
}

Firebase Synchronization (Live Sessions Only):

For live TiQer sessions, navigation triggers real-time Firebase updates:

{
    "firebase_sync": {
        "path": "/sessions/{session_token}/navigation",
        "sync_timestamp": "ISO_8601_timestamp",
        "sync_status": "Success|Failed|Pending",
        "sync_data": {
            "current_question": "integer",
            "navigation_source": "webapp|mobile",
            "synchronized_devices": ["device_id_1", "device_id_2"]
        }
    }
}

Error Handling

Common Error Scenarios:

1. Session/Activity Not Found

{
    "status": "FAILURE",
    "error_message": "Session or activity not found",
    "error_code": "RESOURCE_NOT_FOUND",
    "data": {
        "resource_type": "TiQerSession|Activity",
        "resource_id": "session_token|activity_id",
        "available_resources": []
    }
}

2. Navigation Boundary Errors

{
    "status": "FAILURE",
    "error_message": "Cannot navigate beyond question boundaries",
    "error_code": "NAVIGATION_BOUNDARY_ERROR",
    "data": {
        "boundary_type": "beginning|end",
        "current_position": "integer",
        "total_questions": "integer",
        "suggested_action": "string"
    }
}

3. Firebase Sync Failures (Live Sessions)

{
    "status": "FAILURE",
    "error_message": "Firebase synchronization failed",
    "error_code": "FIREBASE_SYNC_ERROR",
    "data": {
        "firebase_status": "Disconnected|Error",
        "fallback_active": true,
        "navigation_completed": true,
        "sync_retry_in_seconds": 30
    }
}

4. Access Control Errors

{
    "status": "FAILURE",
    "error_message": "Insufficient permissions for navigation",
    "error_code": "ACCESS_DENIED",
    "data": {
        "user_role": "string",
        "required_permission": "string",
        "resource_access": "denied"
    }
}

Error Codes:

SESSION_NOT_FOUND: TiQer session does not exist
ACTIVITY_NOT_FOUND: Individual quiz activity not found
ACCESS_DENIED: User lacks permission for resource
END_OF_QUESTIONS: Attempted to navigate past last question
BEGINNING_OF_QUESTIONS: Attempted to navigate before first question
FIREBASE_SYNC_ERROR: Real-time synchronization failed
INVALID_SOURCE: Source parameter is invalid
NAVIGATION_LOCKED: Navigation is temporarily disabled
SESSION_INACTIVE: Session is not in active state

Source Tracking and Analytics:

All navigation requests include source tracking for analytics:

{
    "source_tracking": {
        "navigation_source": "webapp|mobile",
        "user_agent": "string",
        "ip_address": "string",
        "timestamp": "ISO_8601_timestamp",
        "session_duration": "seconds"
    }
}

This enables comprehensive analytics on platform usage patterns and user behavior across WebApp and Mobile platforms.

timmapuramreddy/XP-I3068_API_DOCUMENTATION.md

Select an option

No results found

Select an option

No results found

XP-I3068: Enhanced Navigation APIs for TiQer Sessions - API Documentation

Overview

Table of Contents

Authentication

Live TiQer Session Navigation APIs

1. Navigate to Next Question (Live Session)

2. Navigate to Previous Question (Live Session)

3. Get Current Session State

Individual Quiz Navigation APIs

4. Navigate to Next Question (Individual Quiz)

5. Navigate to Previous Question (Individual Quiz)

Navigation Response Format

Standard Navigation Response Structure:

Firebase Synchronization (Live Sessions Only):

Error Handling

Common Error Scenarios:

1. Session/Activity Not Found

2. Navigation Boundary Errors

3. Firebase Sync Failures (Live Sessions)

4. Access Control Errors

Error Codes:

Source Tracking and Analytics: