Skip to content

api reference

Jump to bottom
Mile Shi edited this page May 26, 2025 · 2 revisions

API Reference

Complete API documentation for the Intelligent IDE backend services. This reference covers all endpoints, authentication, data models, and integration patterns.

Base URL and Versioning

Base URL: https://api.intelligentide.com/v1
WebSocket: wss://api.intelligentide.com/ws

API Versioning

  • Current Version: v1
  • Version Header: API-Version: v1
  • Deprecation Policy: 6 months notice for breaking changes

Authentication

JWT Token Authentication

Authorization: Bearer <jwt_token>

Login Endpoint

POST /auth/login
Content-Type: application/json

{
  "email": "user@university.edu",
  "password": "secure_password"
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "user": {
    "id": "user_123",
    "email": "user@university.edu",
    "role": "student",
    "profile": {...}
  }
}

Refresh Token

POST /auth/refresh
Content-Type: application/json

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Core Data Models

User Model

interface User {
  id: string;
  email: string;
  username: string;
  first_name: string;
  last_name: string;
  role: 'student' | 'instructor' | 'admin';
  profile: UserProfile;
  created_at: string;
  updated_at: string;
  is_active: boolean;
}

interface UserProfile {
  avatar_url?: string;
  bio?: string;
  institution?: string;
  department?: string;
  year?: number;
  major?: string;
}

Course Model

interface Course {
  id: string;
  code: string;
  name: string;
  description: string;
  instructor_id: string;
  semester: string;
  year: number;
  status: 'draft' | 'active' | 'archived';
  enrollment_settings: {
    max_students: number;
    self_enrollment: boolean;
    approval_required: boolean;
  };
  created_at: string;
  updated_at: string;
}

Assignment Model

interface Assignment {
  id: string;
  course_id: string;
  title: string;
  description: string;
  instructions: string;
  type: 'individual' | 'group' | 'notebook';
  due_date: string;
  points: number;
  submission_format: string[];
  auto_grading: boolean;
  created_at: string;
  updated_at: string;
}

User Management API

Get Current User

GET /users/me
Authorization: Bearer <token>

Response:

{
  "id": "user_123",
  "email": "student@university.edu",
  "username": "john_doe",
  "first_name": "John",
  "last_name": "Doe",
  "role": "student",
  "profile": {
    "avatar_url": "https://cdn.intelligent-ide.project/avatars/user_123.jpg",
    "bio": "Computer Science student",
    "institution": "University",
    "department": "Computer Science",
    "year": 3
  }
}

Update User Profile

PUT /users/me
Authorization: Bearer <token>
Content-Type: application/json

{
  "first_name": "John",
  "last_name": "Smith",
  "profile": {
    "bio": "Updated bio",
    "year": 4
  }
}

Get User by ID

GET /users/{user_id}
Authorization: Bearer <token>

Course Management API

List Courses

GET /courses
Authorization: Bearer <token>
Query Parameters:
  - page: integer (default: 1)
  - limit: integer (default: 20)
  - status: string (active, archived, draft)
  - instructor_id: string
  - search: string

Response:

{
  "courses": [
    {
      "id": "course_123",
      "code": "CS101",
      "name": "Introduction to Programming",
      "instructor": {
        "id": "instructor_456",
        "name": "Dr. Jane Smith"
      },
      "enrollment_count": 25,
      "status": "active"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 3,
    "total_items": 50,
    "per_page": 20
  }
}

Create Course

POST /courses
Authorization: Bearer <token>
Content-Type: application/json

{
  "code": "CS101",
  "name": "Introduction to Programming",
  "description": "Learn fundamental programming concepts",
  "semester": "Spring",
  "year": 2025,
  "enrollment_settings": {
    "max_students": 30,
    "self_enrollment": false,
    "approval_required": true
  }
}

Get Course Details

GET /courses/{course_id}
Authorization: Bearer <token>

Update Course

PUT /courses/{course_id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Updated Course Name",
  "description": "Updated description"
}

Delete Course

DELETE /courses/{course_id}
Authorization: Bearer <token>

Enrollment API

Enroll Student

POST /courses/{course_id}/enrollments
Authorization: Bearer <token>
Content-Type: application/json

{
  "user_id": "student_123",
  "role": "student"
}

List Course Enrollments

GET /courses/{course_id}/enrollments
Authorization: Bearer <token>
Query Parameters:
  - role: string (student, instructor, ta)
  - status: string (active, pending, dropped)

Update Enrollment

PUT /courses/{course_id}/enrollments/{user_id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "role": "ta",
  "status": "active"
}

Drop from Course

DELETE /courses/{course_id}/enrollments/{user_id}
Authorization: Bearer <token>

Assignment API

List Assignments

GET /courses/{course_id}/assignments
Authorization: Bearer <token>
Query Parameters:
  - status: string (published, draft, archived)
  - due_date_after: string (ISO date)
  - due_date_before: string (ISO date)

Create Assignment

POST /courses/{course_id}/assignments
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "Homework 1: Variables and Functions",
  "description": "Practice with Python basics",
  "instructions": "Complete all exercises in the notebook",
  "type": "individual",
  "due_date": "2025-02-01T23:59:59Z",
  "points": 100,
  "submission_format": ["python", "notebook"],
  "auto_grading": true
}

Get Assignment

GET /assignments/{assignment_id}
Authorization: Bearer <token>

Update Assignment

PUT /assignments/{assignment_id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "due_date": "2025-02-03T23:59:59Z",
  "points": 120
}

Delete Assignment

DELETE /assignments/{assignment_id}
Authorization: Bearer <token>

Submission API

Submit Assignment

POST /assignments/{assignment_id}/submissions
Authorization: Bearer <token>
Content-Type: multipart/form-data

files: File[]
metadata: {
  "submission_text": "My solution explanation",
  "late_submission": false
}

List Submissions

GET /assignments/{assignment_id}/submissions
Authorization: Bearer <token>
Query Parameters:
  - student_id: string
  - status: string (submitted, graded, late)

Get Submission

GET /submissions/{submission_id}
Authorization: Bearer <token>

Grade Submission

PUT /submissions/{submission_id}/grade
Authorization: Bearer <token>
Content-Type: application/json

{
  "score": 85,
  "max_score": 100,
  "feedback": "Good work! Consider optimizing the algorithm in question 3.",
  "rubric_scores": {
    "correctness": 40,
    "style": 15,
    "efficiency": 30
  }
}

File Management API

List Files

GET /courses/{course_id}/files
Authorization: Bearer <token>
Query Parameters:
  - path: string (folder path)
  - type: string (file type filter)
  - search: string (search query)

Upload File

POST /courses/{course_id}/files
Authorization: Bearer <token>
Content-Type: multipart/form-data

file: File
path: string
permissions: {
  "read": ["student"],
  "write": ["instructor"]
}

Download File

GET /files/{file_id}/download
Authorization: Bearer <token>

Update File

PUT /files/{file_id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "content": "Updated file content",
  "commit_message": "Fixed bug in function"
}

Delete File

DELETE /files/{file_id}
Authorization: Bearer <token>

Get File Permissions

GET /files/{file_id}/permissions
Authorization: Bearer <token>

Update File Permissions

PUT /files/{file_id}/permissions
Authorization: Bearer <token>
Content-Type: application/json

{
  "permissions": {
    "read": ["student", "instructor"],
    "write": ["instructor"],
    "admin": ["instructor"]
  }
}

Notebook API

Create Notebook

POST /courses/{course_id}/notebooks
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "Data Analysis Lab",
  "language": "python",
  "template": "data_science",
  "cells": [
    {
      "type": "markdown",
      "content": "# Introduction\n\nThis notebook covers..."
    },
    {
      "type": "code", 
      "content": "import pandas as pd\nimport numpy as np"
    }
  ]
}

Get Notebook

GET /notebooks/{notebook_id}
Authorization: Bearer <token>

Update Notebook

PUT /notebooks/{notebook_id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "cells": [
    {
      "id": "cell_1",
      "type": "code",
      "content": "print('Updated content')"
    }
  ]
}

Execute Cell

POST /notebooks/{notebook_id}/cells/{cell_id}/execute
Authorization: Bearer <token>

Response:

{
  "execution_id": "exec_123",
  "status": "running",
  "output": null
}

Get Execution Result

GET /executions/{execution_id}
Authorization: Bearer <token>

Response:

{
  "execution_id": "exec_123",
  "status": "completed",
  "output": {
    "text": "Hello, World!\n",
    "html": null,
    "error": null,
    "execution_time": 0.002
  }
}

Chat and Communication API

Get Course Chat

GET /courses/{course_id}/chat/messages
Authorization: Bearer <token>
Query Parameters:
  - limit: integer (default: 50)
  - before: string (message ID)
  - after: string (message ID)

Send Message

POST /courses/{course_id}/chat/messages
Authorization: Bearer <token>
Content-Type: application/json

{
  "content": "Has anyone figured out problem 3?",
  "message_type": "text",
  "reply_to": null,
  "attachments": []
}

Direct Message

POST /users/{user_id}/direct_messages
Authorization: Bearer <token>
Content-Type: application/json

{
  "content": "Can you help me with the assignment?",
  "message_type": "text"
}

Real-time Collaboration API

Join Collaboration Session

POST /files/{file_id}/collaboration/join
Authorization: Bearer <token>

Response:

{
  "session_id": "collab_123",
  "websocket_url": "wss://api.intelligentide.com/ws/collaboration/collab_123",
  "participants": [
    {
      "user_id": "user_123",
      "name": "John Doe",
      "cursor_color": "#ff6b6b"
    }
  ]
}

WebSocket Events

// Client -> Server events
interface CollaborationEvent {
  type: 'operation' | 'cursor_update' | 'presence_update';
  data: any;
}

// Server -> Client events
interface CollaborationResponse {
  type: 'operation' | 'cursor_update' | 'user_joined' | 'user_left';
  data: any;
  timestamp: string;
}

Analytics API

Course Analytics

GET /courses/{course_id}/analytics
Authorization: Bearer <token>
Query Parameters:
  - metric: string (engagement, performance, participation)
  - start_date: string
  - end_date: string

Response:

{
  "course_id": "course_123",
  "metrics": {
    "total_students": 25,
    "active_students": 23,
    "average_grade": 87.5,
    "assignment_completion_rate": 0.92,
    "engagement_score": 8.4
  },
  "trends": {
    "daily_activity": [...],
    "weekly_progress": [...]
  }
}

User Progress

GET /users/{user_id}/progress
Authorization: Bearer <token>
Query Parameters:
  - course_id: string

Assignment Analytics

GET /assignments/{assignment_id}/analytics
Authorization: Bearer <token>

Error Responses

Standard Error Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": {
      "field": "email",
      "issue": "Invalid email format"
    },
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "req_123456"
  }
}

Common Error Codes

  • AUTHENTICATION_ERROR (401): Invalid or expired token
  • AUTHORIZATION_ERROR (403): Insufficient permissions
  • VALIDATION_ERROR (400): Invalid request data
  • NOT_FOUND (404): Resource not found
  • CONFLICT (409): Resource already exists
  • RATE_LIMIT_EXCEEDED (429): Too many requests
  • INTERNAL_ERROR (500): Server error

Rate Limiting

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1642123456

Rate Limits by Endpoint Type

  • Authentication: 10 requests/minute
  • File Operations: 100 requests/minute
  • API Queries: 1000 requests/hour
  • WebSocket: 10000 messages/hour

Webhooks

Webhook Configuration

POST /webhooks
Authorization: Bearer <token>
Content-Type: application/json

{
  "url": "https://your-app.com/webhooks/intelligent-ide",
  "events": ["assignment.submitted", "course.enrollment", "grade.updated"],
  "secret": "webhook_secret_key"
}

Webhook Events

{
  "event": "assignment.submitted",
  "data": {
    "assignment_id": "assignment_123",
    "submission_id": "submission_456", 
    "student_id": "student_789",
    "course_id": "course_123",
    "submitted_at": "2025-01-15T10:30:00Z"
  },
  "timestamp": "2025-01-15T10:30:01Z",
  "signature": "sha256=..."
}

SDK and Client Libraries

JavaScript/TypeScript SDK

npm install @intelligent-ide/sdk
import { IntelligentIDE } from '@intelligent-ide/sdk';

const client = new IntelligentIDE({
  apiKey: 'your_api_key',
  baseUrl: 'https://api.intelligentide.com/v1'
});

// List courses
const courses = await client.courses.list();

// Create assignment
const assignment = await client.assignments.create({
  courseId: 'course_123',
  title: 'Homework 1',
  dueDate: '2025-02-01T23:59:59Z'
});

Python SDK

pip install intelligent-ide-sdk
from intelligent_ide import IntelligentIDE

client = IntelligentIDE(
    api_key='your_api_key',
    base_url='https://api.intelligentide.com/v1'
)

# List courses
courses = client.courses.list()

# Submit assignment
submission = client.assignments.submit(
    assignment_id='assignment_123',
    files=['solution.py'],
    metadata={'submission_text': 'My solution'}
)

Testing

Test Environment

Base URL: https://api-test.intelligentide.com/v1
WebSocket: wss://api-test.intelligentide.com/ws

Test Data

Use the /test-data endpoints to create test courses, users, and assignments for development and testing.

POST /test-data/course
Authorization: Bearer <test_token>
Content-Type: application/json

{
  "template": "cs101_intro_programming",
  "student_count": 10
}

This comprehensive API reference provides all the endpoints and patterns needed to integrate with the Intelligent IDE platform! 🚀📚


#### Project Overview
```markdown
<!-- filepath: /Users/shimile/projects/team-project-25spring-36.wiki/Project-Overview.md -->
# Project Overview

## Project Goals
- Define the main objectives of the project.
- Outline the expected outcomes and deliverables.

## Timeline
- Start Date: Spring 2025
- End Date: End of Spring 2025
- Key Milestones: Architecture design, core development, testing phase, deployment

Team Members

<!-- filepath: /Users/shimile/projects/team-project-25spring-36.wiki/Team-Members.md -->
# Team Members

| Name          | Role               | Email                |
|---------------|--------------------|----------------------|
| Alice Smith   | Project Manager     | team-lead@intelligent-ide.project    |
| Bob Johnson   | Developer           | developer@intelligent-ide.project      |
| Carol White   | Designer            | designer@intelligent-ide.project    |
| Dave Brown    | QA Tester           | qa@intelligent-ide.project     |

Meeting Notes

<!-- filepath: /Users/shimile/projects/team-project-25spring-36.wiki/Meeting-Notes.md -->
# Meeting Notes

## Meeting Date: May 2025
### Attendees:
- Alice Smith
- Bob Johnson
- Carol White
- Dave Brown

### Agenda:
1. Project updates
2. Discuss challenges
3. Plan next steps

### Notes:
- [Insert notes from the meeting]

Resources

<!-- filepath: /Users/shimile/projects/team-project-25spring-36.wiki/Resources.md -->
# Resources

- [Project Management Tool](link-to-tool)
- [Design Guidelines](link-to-guidelines)
- [Coding Standards](link-to-standards)
- [Documentation Templates](link-to-templates)

FAQs

<!-- filepath: /Users/shimile/projects/team-project-25spring-36.wiki/FAQs.md -->
# Frequently Asked Questions

## Q1: What is the main goal of the project?
A1: [Insert answer]

## Q2: How often do we meet?
A2: [Insert answer]

## Q3: Where can I find the project documentation?
A3: [Insert answer]

Contact Information

<!-- filepath: /Users/shimile/projects/team-project-25spring-36.wiki/Contact-Information.md -->
# Contact Information

For any inquiries or issues, please reach out to the following contacts:

- **Project Manager:** Alice Smith - team-lead@intelligent-ide.project
- **Technical Support:** Bob Johnson - developer@intelligent-ide.project

Conclusion

This structure provides a comprehensive overview of the project and serves as a guide for team members. You can expand each section with more detailed information as the project progresses. Make sure to keep the wiki updated with the latest information and resources.

🏠 Home

📖 User Guide

🛠️ Developer Guide

⭐ Features

📚 Tutorials

Clone this wiki locally