File "API_DOCUMENTATION.md"

Full Path: /home/u534186629/domains/tuitionalai.com/public_html/platform/API_DOCUMENTATION.md
File size: 11.07 KB
MIME-type: text/plain
Charset: utf-8

# Tuitional AI API Documentation

This document outlines the API endpoints required by the Tuitional AI frontend application.

## Base URL

All API endpoints should be accessible from a base URL: `https://api.tuitional.ai/v1` or your own domain.

## Authentication

### Authentication Headers

All authenticated endpoints require an Authorization header:

```
Authorization: Bearer <token>
```

### Authentication Endpoints

#### Register User

- **URL**: `/auth/register`
- **Method**: `POST`
- **Description**: Creates a new user account
- **Request Body**:
  ```json
  {
    "email": "user@example.com",
    "password": "securePassword123",
    "fullName": "John Doe",
    "role": "student" // or "teacher" or "admin"
  }
  ```
- **Response**: 
  ```json
  {
    "token": "jwt_token_here",
    "user": {
      "id": "user_id",
      "email": "user@example.com",
      "role": "student",
      "profileCompleted": false,
      "fullName": "John Doe"
    }
  }
  ```

#### Login User

- **URL**: `/auth/login`
- **Method**: `POST`
- **Description**: Authenticates a user and returns a token
- **Request Body**:
  ```json
  {
    "email": "user@example.com",
    "password": "securePassword123"
  }
  ```
- **Response**: 
  ```json
  {
    "token": "jwt_token_here",
    "user": {
      "id": "user_id",
      "email": "user@example.com",
      "role": "student",
      "profileCompleted": true,
      "fullName": "John Doe"
    }
  }
  ```

#### Verify Token

- **URL**: `/auth/verify`
- **Method**: `POST`
- **Description**: Verifies if a token is valid
- **Request Body**:
  ```json
  {
    "token": "jwt_token_here"
  }
  ```
- **Response**: 
  ```json
  {
    "valid": true,
    "user": {
      "id": "user_id",
      "email": "user@example.com",
      "role": "student",
      "profileCompleted": true,
      "fullName": "John Doe"
    }
  }
  ```

## User Profiles

### Student Profiles

#### Create/Update Student Profile

- **URL**: `/profile/student`
- **Method**: `POST`
- **Description**: Creates or updates a student profile
- **Authentication**: Required
- **Request Body**:
  ```json
  {
    "fullName": "John Doe",
    "phoneNumber": "123-456-7890",
    "grade": "Grade 10",
    "curriculum": "CAIE",
    "level": "Intermediate",
    "country": "United States",
    "school": "International School"
  }
  ```
- **Response**: 
  ```json
  {
    "userId": "user_id",
    "fullName": "John Doe",
    "phoneNumber": "123-456-7890",
    "grade": "Grade 10",
    "curriculum": "CAIE",
    "level": "Intermediate",
    "country": "United States",
    "school": "International School"
  }
  ```

#### Get Student Profile

- **URL**: `/profile/student/:userId`
- **Method**: `GET`
- **Description**: Retrieves a student's profile
- **Authentication**: Required
- **Response**: 
  ```json
  {
    "userId": "user_id",
    "fullName": "John Doe",
    "phoneNumber": "123-456-7890",
    "grade": "Grade 10",
    "curriculum": "CAIE",
    "level": "Intermediate",
    "country": "United States",
    "school": "International School"
  }
  ```

### Teacher Profiles

#### Create/Update Teacher Profile

- **URL**: `/profile/teacher`
- **Method**: `POST`
- **Description**: Creates or updates a teacher profile
- **Authentication**: Required
- **Request Body**:
  ```json
  {
    "fullName": "Jane Smith",
    "phoneNumber": "987-654-3210",
    "grade": "Multiple",
    "curriculum": "CAIE",
    "level": "Advanced",
    "country": "United Kingdom",
    "school": "Cambridge Academy",
    "position": "Science Teacher"
  }
  ```
- **Response**: 
  ```json
  {
    "userId": "user_id",
    "fullName": "Jane Smith",
    "phoneNumber": "987-654-3210",
    "grade": "Multiple",
    "curriculum": "CAIE",
    "level": "Advanced",
    "country": "United Kingdom",
    "school": "Cambridge Academy",
    "position": "Science Teacher"
  }
  ```

#### Get Teacher Profile

- **URL**: `/profile/teacher/:userId`
- **Method**: `GET`
- **Description**: Retrieves a teacher's profile
- **Authentication**: Required
- **Response**: 
  ```json
  {
    "userId": "user_id",
    "fullName": "Jane Smith",
    "phoneNumber": "987-654-3210",
    "grade": "Multiple",
    "curriculum": "CAIE",
    "level": "Advanced",
    "country": "United Kingdom",
    "school": "Cambridge Academy",
    "position": "Science Teacher"
  }
  ```

## MindPages

### Get MindPages

- **URL**: `/mindpage/user/:userId`
- **Method**: `GET`
- **Description**: Retrieves all mind pages for a specific user
- **Authentication**: Required
- **Response**: 
  ```json
  [
    {
      "id": "page_id_1",
      "user_id": "user_id",
      "title": "Chemistry Notes",
      "content": "<p>These are my chemistry notes.</p>",
      "tags": ["chemistry", "notes"],
      "folder_path": "root",
      "page_type": "note",
      "is_starred": false,
      "shared_with": [],
      "created_at": "2023-04-15T10:00:00Z",
      "updated_at": "2023-04-15T10:30:00Z"
    },
    {
      "id": "page_id_2",
      "user_id": "user_id",
      "title": "Physics Formulas",
      "content": "<p>Key physics formulas.</p>",
      "tags": ["physics", "formulas"],
      "folder_path": "root",
      "page_type": "note",
      "is_starred": true,
      "shared_with": [],
      "created_at": "2023-04-16T10:00:00Z",
      "updated_at": "2023-04-16T10:30:00Z"
    }
  ]
  ```

### Get Single MindPage

- **URL**: `/mindpage/:id`
- **Method**: `GET`
- **Description**: Retrieves a specific mind page by ID
- **Authentication**: Required
- **Response**: 
  ```json
  {
    "id": "page_id",
    "user_id": "user_id",
    "title": "Chemistry Notes",
    "content": "<p>These are my chemistry notes.</p>",
    "tags": ["chemistry", "notes"],
    "folder_path": "root",
    "page_type": "note",
    "is_starred": false,
    "shared_with": [],
    "created_at": "2023-04-15T10:00:00Z",
    "updated_at": "2023-04-15T10:30:00Z"
  }
  ```

### Create MindPage

- **URL**: `/mindpage`
- **Method**: `POST`
- **Description**: Creates a new mind page
- **Authentication**: Required
- **Request Body**:
  ```json
  {
    "userId": "user_id",
    "title": "New Study Notes",
    "content": "<p>This is the content of my notes.</p>",
    "tags": ["study", "notes"],
    "folder_path": "root",
    "page_type": "note"
  }
  ```
- **Response**: 
  ```json
  {
    "id": "new_page_id",
    "user_id": "user_id",
    "title": "New Study Notes",
    "content": "<p>This is the content of my notes.</p>",
    "tags": ["study", "notes"],
    "folder_path": "root",
    "page_type": "note",
    "is_starred": false,
    "shared_with": [],
    "created_at": "2023-04-20T15:00:00Z",
    "updated_at": "2023-04-20T15:00:00Z"
  }
  ```

### Update MindPage

- **URL**: `/mindpage/:id`
- **Method**: `PUT`
- **Description**: Updates an existing mind page
- **Authentication**: Required
- **Request Body**:
  ```json
  {
    "title": "Updated Study Notes",
    "content": "<p>This is the updated content.</p>",
    "tags": ["study", "notes", "updated"],
    "is_starred": true
  }
  ```
- **Response**: 
  ```json
  {
    "id": "page_id",
    "user_id": "user_id",
    "title": "Updated Study Notes",
    "content": "<p>This is the updated content.</p>",
    "tags": ["study", "notes", "updated"],
    "folder_path": "root",
    "page_type": "note",
    "is_starred": true,
    "shared_with": [],
    "created_at": "2023-04-20T15:00:00Z",
    "updated_at": "2023-04-20T15:30:00Z"
  }
  ```

### Delete MindPage

- **URL**: `/mindpage/:id`
- **Method**: `DELETE`
- **Description**: Deletes a mind page
- **Authentication**: Required
- **Response**: 
  ```json
  {
    "success": true,
    "message": "Mind page deleted successfully"
  }
  ```

### Share MindPage

- **URL**: `/mindpage/:id/share`
- **Method**: `PUT`
- **Description**: Shares a mind page with other users
- **Authentication**: Required
- **Request Body**:
  ```json
  {
    "sharedWith": ["user_id_1", "user_id_2"]
  }
  ```
- **Response**: 
  ```json
  {
    "success": true,
    "message": "Mind page shared successfully"
  }
  ```

## Groups

### Get User Groups

- **URL**: `/groups/user/:userId`
- **Method**: `GET`
- **Description**: Retrieves all groups a user belongs to
- **Authentication**: Required
- **Response**: 
  ```json
  [
    {
      "id": "group_id_1",
      "name": "Physics Study Group",
      "description": "A group for studying physics",
      "owner_id": "owner_user_id",
      "created_at": "2023-04-10T12:00:00Z",
      "members": [
        {
          "user_id": "user_id",
          "role": "member",
          "joined_at": "2023-04-11T10:00:00Z"
        }
      ]
    }
  ]
  ```

### Create Group

- **URL**: `/groups`
- **Method**: `POST`
- **Description**: Creates a new group
- **Authentication**: Required
- **Request Body**:
  ```json
  {
    "name": "Chemistry Study Group",
    "description": "A group for studying chemistry",
    "owner_id": "user_id"
  }
  ```
- **Response**: 
  ```json
  {
    "id": "new_group_id",
    "name": "Chemistry Study Group",
    "description": "A group for studying chemistry",
    "owner_id": "user_id",
    "created_at": "2023-04-20T15:00:00Z",
    "members": [
      {
        "user_id": "user_id",
        "role": "owner",
        "joined_at": "2023-04-20T15:00:00Z"
      }
    ]
  }
  ```

### Invite to Group

- **URL**: `/groups/:groupId/invite`
- **Method**: `POST`
- **Description**: Invites a user to a group
- **Authentication**: Required
- **Request Body**:
  ```json
  {
    "email": "invited_user@example.com",
    "invited_by": "user_id"
  }
  ```
- **Response**: 
  ```json
  {
    "success": true,
    "message": "Invitation sent successfully",
    "invitation_id": "invitation_id"
  }
  ```

### Accept Invitation

- **URL**: `/groups/invitations/:invitationId/accept`
- **Method**: `POST`
- **Description**: Accepts a group invitation
- **Authentication**: Required
- **Request Body**:
  ```json
  {
    "userId": "invited_user_id"
  }
  ```
- **Response**: 
  ```json
  {
    "success": true,
    "message": "You've been added to the group",
    "group_id": "group_id"
  }
  ```

## Error Handling

All API endpoints should return appropriate HTTP status codes:

- `200 OK`: The request was successful
- `201 Created`: A resource was successfully created
- `400 Bad Request`: The request was invalid
- `401 Unauthorized`: Authentication is required
- `403 Forbidden`: The user does not have permission
- `404 Not Found`: The requested resource was not found
- `500 Internal Server Error`: An error occurred on the server

Error responses should have this structure:

```json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  }
}
```

## Implementation Notes

1. **Security**: Implement proper validation for all inputs
2. **Rate Limiting**: Consider implementing rate limiting to prevent abuse
3. **CORS**: Configure CORS to allow requests from the frontend domain
4. **Pagination**: For endpoints that return lists, consider implementing pagination
5. **Caching**: Implement appropriate caching strategies for read-heavy endpoints
6. **Logging**: Log API requests for debugging and monitoring purposes
7. **Documentation**: Keep this documentation updated as the API evolves

This documentation provides a basic structure for the backend API. Extend it as needed to support additional features of the Tuitional AI application.