🔌Documentación de API - ToLearn

Esta documentación describe los endpoints, WebSockets y servicios web disponibles en la plataforma ToLearn.

📋 Tabla de Contenidos

• Visión General

• Autenticación

• Endpoints HTTP

• WebSocket API

• Modelos de Datos

• Códigos de Respuesta

• Ejemplos de Uso

🎯 Visión General

URL Base

Producción: https://tolearn.online
Desarrollo: http://localhost:8000

Formato de Respuesta

Todas las respuestas están en formato JSON (excepto archivos multimedia):

{
  "status": "success|error",
  "data": { },
  "message": "Mensaje descriptivo",
  "timestamp": "2024-12-10T10:30:00Z"
}

Versionado

Actualmente la API es v1. Las versiones futuras incluirán prefijo:

/api/v1/...
/api/v2/...

🔐 Autenticación

Autenticación Basada en Sesión

ToLearn usa autenticación basada en sesión de Django por defecto.

Login

POST /login/
Content-Type: application/x-www-form-urlencoded

[email protected]&password=contraseña123

Respuesta Exitosa:

HTTP/1.1 302 Found
Location: /dashboard/main/
Set-Cookie: sessionid=abc123...; HttpOnly; Secure

Logout

POST /logout/

Respuesta:

HTTP/1.1 302 Found
Location: /login/

CSRF Protection

Todas las solicitudes POST requieren token CSRF:

POST /endpoint/
X-CSRFToken: <token-csrf>
Cookie: csrftoken=<token-csrf>

Obtener token CSRF:

// En JavaScript
const csrftoken = document.querySelector('[name=csrfmiddlewaretoken]').value;

OAuth 2.0 (Google)

URL de autorización: /accounts/google/login/
Callback URL: /accounts/google/login/callback/

🌐 Endpoints HTTP

Autenticación

POST /login/

Iniciar sesión con credenciales.

Parámetros:

• email (string): Email o username

• password (string): Contraseña

Respuesta:

{
  "status": "success",
  "redirect": "/dashboard/main/"
}

POST /signup/

Registrar nueva cuenta.

Parámetros:

• username (string): Nombre de usuario único

• email (string): Email válido

• password (string): Contraseña (min 8 caracteres)

• confirm_password (string): Confirmación

Respuesta:

{
  "status": "success",
  "message": "Usuario creado exitosamente",
  "redirect": "/login/"
}

Cursos

GET /courses/

Listar todos los cursos disponibles para el usuario.

Respuesta:

{
  "courses": [
    {
      "id": 1,
      "title": "Introducción a la Biología",
      "description": "Curso completo de biología...",
      "status": "Activo",
      "photo_url": "https://s3.../photo.jpg",
      "lessons_count": 12,
      "progress": 45
    }
  ]
}

GET /courses/{id}/

Obtener detalles de un curso específico.

Parámetros de URL:

• id (int): ID del curso

Respuesta:

{
  "id": 1,
  "title": "Introducción a la Biología",
  "description": "Descripción completa...",
  "status": "Activo",
  "lessons": [
    {
      "id": 1,
      "order": 1,
      "title": "La Célula",
      "is_active": true,
      "completed": true
    }
  ]
}

GET /courses/{course_id}/lessons/{lesson_id}/

Ver contenido de una lección.

Respuesta:

{
  "id": 1,
  "title": "La Célula",
  "description": "<p>Contenido HTML...</p>",
  "tasks": [
    {
      "id": 1,
      "title": "Tarea 1",
      "type": "homework"
    }
  ],
  "materials": [
    {
      "id": 1,
      "title": "Guía de Estudio",
      "type": "file",
      "url": "https://s3.../material.pdf"
    }
  ]
}

Evaluaciones

GET /dashboard/assignments/

Listar evaluaciones del usuario.

Parámetros de Query:

• status (string): pending|completed|all

• type (string): homework|exam

• limit (int): Número de resultados (default: 20)

• offset (int): Offset para paginación

Respuesta:

{
  "count": 15,
  "next": "/dashboard/assignments/?offset=20",
  "previous": null,
  "results": [
    {
      "id": 1,
      "title": "Examen Final de Biología",
      "type": "exam",
      "difficulty": "hard",
      "due_date": "2024-12-15T23:59:00Z",
      "time_limit": 60,
      "submitted": false,
      "score": null
    }
  ]
}

GET /dashboard/assignments/{id}/

Obtener detalles de una evaluación.

Respuesta:

{
  "id": 1,
  "title": "Examen Final",
  "description": "<p>Este examen cubre...</p>",
  "type": "exam",
  "time_limit": 60,
  "due_date": "2024-12-15T23:59:00Z",
  "require_fullscreen": true,
  "questions": [
    {
      "id": 1,
      "order": 1,
      "question_text": "¿Cuál es la capital de España?",
      "question_type": "multiple_choice",
      "points": 5,
      "options": [
        {"id": 1, "option_text": "Madrid", "is_correct": false},
        {"id": 2, "option_text": "Barcelona", "is_correct": false}
      ]
    }
  ]
}

POST /dashboard/assignments/{id}/submit/

Enviar respuestas de una evaluación.

Body:

{
  "answers": [
    {
      "question_id": 1,
      "answer_text": "Madrid",
      "selected_option_id": 1
    },
    {
      "question_id": 2,
      "answer_text": "Respuesta larga...",
      "selected_option_id": null
    }
  ],
  "time_spent": 3600
}

Respuesta:

{
  "status": "success",
  "submission_id": 123,
  "score": 85,
  "max_score": 100,
  "percentage": 85,
  "graded": true,
  "message": "Evaluación enviada exitosamente"
}

Calificaciones

GET /dashboard/submissions/{id}/

Ver resultado de un envío.

Respuesta:

{
  "id": 123,
  "assignment": {
    "id": 1,
    "title": "Examen Final"
  },
  "student": {
    "id": 5,
    "username": "juan.perez"
  },
  "score": 85,
  "max_score": 100,
  "submitted_at": "2024-12-10T14:30:00Z",
  "graded_at": "2024-12-10T16:00:00Z",
  "status": "graded",
  "teacher_comment": "Excelente trabajo!",
  "answers": [
    {
      "question_id": 1,
      "question_text": "¿Cuál es la capital de España?",
      "student_answer": "Madrid",
      "is_correct": true,
      "points_earned": 5,
      "points_possible": 5,
      "feedback": "Correcto!"
    }
  ]
}

Webinars

GET /webinar/rooms/

Listar salas de webinar.

Respuesta:

{
  "rooms": [
    {
      "name": "biologia-clase-3a",
      "display_name": "Clase de Biología 3-A",
      "is_active": true,
      "participants_count": 15,
      "created_at": "2024-12-10T14:00:00Z"
    }
  ]
}

POST /webinar/{room_name}/update_miro_url/

Actualizar URL de pizarra Miro.

Body:

{
  "miro_url": "https://miro.com/app/board/abc123"
}

Respuesta:

{
  "status": "success",
  "miro_url": "https://miro.com/app/board/abc123"
}

Archivos

POST /webinar/{room_name}/upload_file/

Subir archivo a sala de webinar.

Content-Type: multipart/form-data

Parámetros:

• file (file): Archivo a subir

Respuesta:

{
  "status": "success",
  "file": {
    "id": 1,
    "filename": "presentacion.pdf",
    "url": "https://s3.../presentacion.pdf",
    "size": 1024000,
    "uploaded_at": "2024-12-10T15:30:00Z"
  }
}

Perfil de Usuario

GET /dashboard/profile/

Obtener perfil del usuario actual.

Respuesta:

{
  "id": 5,
  "username": "juan.perez",
  "email": "[email protected]",
  "first_name": "Juan",
  "last_name": "Pérez",
  "profile": {
    "language_preference": "es",
    "avatar_url": "https://s3.../avatar.jpg",
    "bio": "Estudiante de tercer año...",
    "notification_settings": {
      "email_assignments": true,
      "email_reminders": true,
      "email_comments": true
    }
  }
}

PATCH /dashboard/profile/

Actualizar perfil.

Body:

{
  "first_name": "Juan",
  "last_name": "Pérez López",
  "profile": {
    "language_preference": "es",
    "bio": "Nueva biografía..."
  }
}

Idioma

POST /set_language/

Cambiar idioma de la interfaz.

Parámetros:

• lang (string): es|en|ru

Respuesta:

HTTP/1.1 302 Found
Location: <página anterior>

🔌 WebSocket API

Conexión WebSocket

const socket = new WebSocket('wss://tolearn.online/ws/webinar/room-name/');

socket.onopen = function(e) {
    console.log('Conectado al webinar');
};

socket.onmessage = function(e) {
    const data = JSON.parse(e.data);
    handleMessage(data);
};

socket.onclose = function(e) {
    console.log('Desconectado');
};

socket.onerror = function(e) {
    console.error('Error WebSocket:', e);
};

Eventos WebSocket - Webinar

Enviar Mensaje de Chat

socket.send(JSON.stringify({
    'type': 'chat_message',
    'message': 'Hola a todos!',
    'username': 'juan.perez'
}));

Respuesta broadcast:

{
  "type": "chat_message",
  "message": "Hola a todos!",
  "username": "juan.perez",
  "timestamp": "2024-12-10T15:30:00Z"
}

Levantar la Mano

socket.send(JSON.stringify({
    'type': 'hand_raised',
    'username': 'juan.perez'
}));

Actualizar Pizarra

socket.send(JSON.stringify({
    'type': 'whiteboard_update',
    'data': {
        'action': 'draw',
        'coordinates': [[100, 150], [110, 160]],
        'color': '#000000'
    }
}));

Compartir Archivo

socket.send(JSON.stringify({
    'type': 'file_shared',
    'file_id': 123,
    'filename': 'presentacion.pdf',
    'url': 'https://s3.../file.pdf'
}));

Actualizar Participantes

// Automático al conectar/desconectar
{
  "type": "participants_update",
  "participants": [
    {"username": "profesor", "role": "teacher"},
    {"username": "juan.perez", "role": "student"}
  ],
  "count": 15
}

📊 Modelos de Datos

User (Usuario)

{
  "id": 5,
  "username": "juan.perez",
  "email": "[email protected]",
  "first_name": "Juan",
  "last_name": "Pérez",
  "is_active": true,
  "is_staff": false,
  "is_superuser": false,
  "date_joined": "2024-09-01T00:00:00Z",
  "last_login": "2024-12-10T14:00:00Z",
  "groups": ["student"]
}

Course (Curso)

{
  "id": 1,
  "title": "Introducción a la Biología",
  "description": "Curso completo de biología celular...",
  "photo": "https://s3.../course-photo.jpg",
  "status": "Activo",
  "created_at": "2024-09-01T00:00:00Z",
  "updated_at": "2024-12-01T00:00:00Z"
}

Lesson (Lección)

{
  "id": 1,
  "course_id": 1,
  "order": 1,
  "sidebar_title": "1. La Célula",
  "title": "Lección 1: Estructura Celular",
  "header": "Descubre la unidad básica de la vida",
  "description": "<p>HTML content...</p>",
  "hashtags": "célula, biología, procariota",
  "is_active": true,
  "activation_date": "2024-09-01 00:00",
  "deactivation_date": null
}

Assignment (Evaluación)

{
  "id": 1,
  "title": "Examen Final de Biología",
  "subject": "Biología",
  "description": "<p>Este examen cubre...</p>",
  "difficulty": "hard",
  "type": "exam",
  "due_date": "2024-12-15T23:59:00Z",
  "time_limit": 60,
  "require_fullscreen": true,
  "fullscreen_exit_attempts": 3,
  "created_at": "2024-11-01T00:00:00Z"
}

Question (Pregunta)

{
  "id": 1,
  "assignment_id": 1,
  "order": 1,
  "question_text": "¿Cuál es la capital de España?",
  "question_type": "multiple_choice",
  "points": 5,
  "explanation": "Madrid es la capital desde 1561",
  "options": [
    {
      "id": 1,
      "option_text": "Madrid",
      "is_correct": true,
      "order": 1
    },
    {
      "id": 2,
      "option_text": "Barcelona",
      "is_correct": false,
      "order": 2
    }
  ]
}

Submission (Envío)

{
  "id": 123,
  "assignment_id": 1,
  "student_id": 5,
  "score": 85,
  "max_score": 100,
  "submitted_at": "2024-12-10T14:30:00Z",
  "graded_at": "2024-12-10T16:00:00Z",
  "status": "graded",
  "time_spent": 3600,
  "teacher_comment": "Excelente trabajo!"
}

Answer (Respuesta)

{
  "id": 456,
  "submission_id": 123,
  "question_id": 1,
  "answer_text": "Madrid",
  "selected_option_id": 1,
  "is_correct": true,
  "points_earned": 5,
  "points_possible": 5,
  "teacher_feedback": "Correcto!"
}

⚠️ Códigos de Respuesta

Códigos HTTP

Código	Significado	Descripción
200	OK	Solicitud exitosa
201	Created	Recurso creado exitosamente
204	No Content	Exitoso sin contenido
302	Found	Redirección
400	Bad Request	Solicitud malformada
401	Unauthorized	No autenticado
403	Forbidden	Sin permisos
404	Not Found	Recurso no encontrado
405	Method Not Allowed	Método HTTP no permitido
500	Internal Server Error	Error del servidor
502	Bad Gateway	Gateway inválido
503	Service Unavailable	Servicio no disponible

Mensajes de Error

{
  "status": "error",
  "code": "INVALID_CREDENTIALS",
  "message": "Email o contraseña incorrectos",
  "details": {
    "field": "password",
    "reason": "invalid"
  }
}

Códigos de Error Comunes:

• INVALID_CREDENTIALS: Credenciales inválidas

• PERMISSION_DENIED: Sin permisos

• RESOURCE_NOT_FOUND: Recurso no encontrado

• VALIDATION_ERROR: Error de validación

• ALREADY_SUBMITTED: Ya enviado

• TIME_EXPIRED: Tiempo expirado

• DUPLICATE_ENTRY: Entrada duplicada

💡 Ejemplos de Uso

Python (requests)

import requests

# Login
session = requests.Session()
login_url = 'https://tolearn.online/login/'

# Obtener CSRF token
response = session.get(login_url)
csrftoken = session.cookies['csrftoken']

# Login
login_data = {
    'email': '[email protected]',
    'password': 'contraseña123',
    'csrfmiddlewaretoken': csrftoken
}
response = session.post(login_url, data=login_data)

# Obtener cursos
courses_url = 'https://tolearn.online/courses/'
response = session.get(courses_url)
courses = response.json()

print(f"Cursos disponibles: {len(courses['courses'])}")

JavaScript (Fetch API)

// Login
async function login(email, password) {
    const csrftoken = getCookie('csrftoken');
    
    const response = await fetch('/login/', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded',
            'X-CSRFToken': csrftoken
        },
        body: `email=${email}&password=${password}`,
        credentials: 'include'
    });
    
    if (response.redirected) {
        window.location.href = response.url;
    }
}

// Obtener cursos
async function getCourses() {
    const response = await fetch('/courses/', {
        credentials: 'include'
    });
    const data = await response.json();
    return data.courses;
}

// Enviar evaluación
async function submitAssignment(assignmentId, answers) {
    const csrftoken = getCookie('csrftoken');
    
    const response = await fetch(`/dashboard/assignments/${assignmentId}/submit/`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'X-CSRFToken': csrftoken
        },
        body: JSON.stringify({ answers }),
        credentials: 'include'
    });
    
    return await response.json();
}

// Función helper para CSRF
function getCookie(name) {
    let cookieValue = null;
    if (document.cookie && document.cookie !== '') {
        const cookies = document.cookie.split(';');
        for (let i = 0; i < cookies.length; i++) {
            const cookie = cookies[i].trim();
            if (cookie.substring(0, name.length + 1) === (name + '=')) {
                cookieValue = decodeURIComponent(cookie.substring(name.length + 1));
                break;
            }
        }
    }
    return cookieValue;
}

cURL

# Login
curl -c cookies.txt -b cookies.txt \
  -X POST https://tolearn.online/login/ \
  -d "[email protected]" \
  -d "password=contraseña123"

# Obtener cursos
curl -b cookies.txt \
  https://tolearn.online/courses/

# Enviar evaluación
curl -b cookies.txt \
  -X POST https://tolearn.online/dashboard/assignments/1/submit/ \
  -H "Content-Type: application/json" \
  -H "X-CSRFToken: <csrf-token>" \
  -d '{"answers":[{"question_id":1,"answer_text":"Madrid"}]}'

📚 Recursos Adicionales

• Django REST Framework

• Django Channels

• WebSocket API

🔄 Changelog

v1.0 (Actual)

• API básica HTTP

• WebSocket para webinars

• Autenticación por sesión

• CRUD de cursos y evaluaciones

Futuro (v2.0)

• REST API completa

• Token authentication (JWT)

• GraphQL support

• Webhooks

• Rate limiting

• API versioning

---

Documentación actualizada: Diciembre 2024