# Material API Documentation

This documentation covers the endpoints for Materials with comprehensive filtering capabilities.

## Authentication
All endpoints require authentication using Sanctum tokens. Include the token in the Authorization header:
```
Authorization: Bearer {your-token}
```

## Material Endpoints

### 1. Get All Materials
**GET** `/api/materials`

Returns a list of materials with optional filtering.

#### Query Parameters
- `title` (string, optional) - Filter by title (partial match)
- `main_category_id` (integer, optional) - Filter by main category ID
- `main_category` (string, optional) - Filter by main category name or code (partial match)
- `sub_category_id` (integer, optional) - Filter by sub category ID
- `sub_category` (string, optional) - Filter by sub category name or code (partial match)
- `is_premium` (boolean, optional) - Filter by premium status (true/false)
- `content` (string, optional) - Search in content field (partial match)
- `sort_by` (string, optional) - Sort column: `id`, `title`, `display_order`, `created_at`, `updated_at` (default: display_order)
- `sort_direction` (string, optional) - Sort direction: `asc`, `desc` (default: asc)
- `paginate` (boolean, optional) - Enable pagination (default: false)
- `per_page` (integer, optional) - Items per page when paginated (max: 100, default: 10)

#### Example Requests
```bash
# Get all materials
GET /api/materials

# Filter by title and category
GET /api/materials?title=mathematics&main_category_id=1

# Filter by main category name
GET /api/materials?main_category=science

# Get premium materials with pagination
GET /api/materials?is_premium=true&paginate=true&per_page=20

# Search in content
GET /api/materials?content=equation&sort_by=title&sort_direction=asc
```

#### Response Format
```json
{
    "success": true,
    "message": "Materials retrieved successfully",
    "data": [
        {
            "id": 1,
            "title": "Introduction to Algebra",
            "content": "Comprehensive guide to algebraic concepts...",
            "thumbnail": "thumbnail_url",
            "main_category_id": 1,
            "sub_category_id": 2,
            "is_premium": true,
            "display_order": 1,
            "created_at": "2024-01-15T10:00:00Z",
            "updated_at": "2024-01-15T10:00:00Z",
            "main_category": {
                "id": 1,
                "name": "Mathematics",
                "code": "MATH",
                "description": "Mathematics subjects"
            },
            "sub_category": {
                "id": 2,
                "name": "Algebra",
                "code": "ALG",
                "description": "Algebraic concepts"
            }
        }
    ],
    "total": 15,
    "pagination": {
        "current_page": 1,
        "last_page": 2,
        "per_page": 10,
        "total": 15,
        "from": 1,
        "to": 10,
        "has_more_pages": true,
        "prev_page_url": null,
        "next_page_url": "http://api/materials?page=2"
    }
}
```

### 2. Get Materials by Main Category
**GET** `/api/materials/main-category/{categoryId}`

Returns materials for a specific main category.

#### Path Parameters
- `categoryId` (integer, required) - Main category ID

#### Query Parameters
- `title` (string, optional) - Filter by title (partial match)
- `is_premium` (boolean, optional) - Filter by premium status

#### Example Requests
```bash
# Get all materials in category 1
GET /api/materials/main-category/1

# Get materials in category 1 with title filter
GET /api/materials/main-category/1?title=algebra

# Get only premium materials in category 1
GET /api/materials/main-category/1?is_premium=true
```

#### Response Format
```json
{
    "success": true,
    "message": "Materials retrieved successfully",
    "data": [...],
    "category": {
        "id": 1,
        "name": "Mathematics",
        "code": "MATH",
        "description": "Mathematics subjects"
    },
    "total": 8
}
```

### 3. Get Materials by Sub Category
**GET** `/api/materials/sub-category/{subCategoryId}`

Returns materials for a specific sub category.

#### Path Parameters
- `subCategoryId` (integer, required) - Sub category ID

#### Query Parameters
- `title` (string, optional) - Filter by title (partial match)
- `is_premium` (boolean, optional) - Filter by premium status

### 4. Get Premium Materials Only
**GET** `/api/materials/premium`

Returns premium materials only.

#### Query Parameters
- `title` (string, optional) - Filter by title (partial match)
- `main_category_id` (integer, optional) - Filter by main category ID

#### Example Requests
```bash
# Get all premium materials
GET /api/materials/premium

# Get premium materials by category
GET /api/materials/premium?main_category_id=1

# Search premium materials by title
GET /api/materials/premium?title=advanced
```

### 5. Get Free Materials Only
**GET** `/api/materials/free`

Returns free (non-premium) materials only.

#### Query Parameters
Same as premium endpoint.

### 6. Search Materials
**GET** `/api/materials/search`

Search materials by title and content.

#### Query Parameters
- `q` (string, required) - Search term to find in title and content
- `main_category_id` (integer, optional) - Filter by main category ID
- `is_premium` (boolean, optional) - Filter by premium status

#### Example Requests
```bash
# Search for materials containing "algebra"
GET /api/materials/search?q=algebra

# Search in specific category
GET /api/materials/search?q=equation&main_category_id=1

# Search only in premium materials
GET /api/materials/search?q=advanced&is_premium=true
```

#### Response Format
```json
{
    "success": true,
    "message": "Search results retrieved successfully",
    "data": [...],
    "search_term": "algebra",
    "total": 5
}
```

### 7. Get Single Material
**GET** `/api/materials/{id}`

Returns details of a specific material.

#### Path Parameters
- `id` (integer, required) - Material ID

#### Example Request
```bash
GET /api/materials/1
```

#### Response Format
```json
{
    "success": true,
    "message": "Material retrieved successfully",
    "data": {
        "id": 1,
        "title": "Introduction to Algebra",
        "content": "Comprehensive guide to algebraic concepts...",
        "thumbnail": "thumbnail_url",
        "main_category_id": 1,
        "sub_category_id": 2,
        "is_premium": true,
        "display_order": 1,
        "main_category": {...},
        "sub_category": {...}
    }
}
```

### 8. Get Categories with Material Counts
**GET** `/api/materials/categories`

Returns all main categories with their material counts.

#### Example Request
```bash
GET /api/materials/categories
```

#### Response Format
```json
{
    "success": true,
    "message": "Categories retrieved successfully",
    "data": [
        {
            "id": 1,
            "name": "Mathematics",
            "code": "MATH",
            "description": "Mathematics subjects",
            "materials_count": 15
        },
        {
            "id": 2,
            "name": "Science",
            "code": "SCI",
            "description": "Science subjects",
            "materials_count": 12
        }
    ]
}
```

## Response Format

All endpoints follow a consistent response format:

### Success Response
```json
{
    "success": true,
    "message": "Resource retrieved successfully",
    "data": [...], // Array of resources or single resource
    "total": 10, // Total count (for lists)
    "pagination": {...} // Pagination info (when paginated)
}
```

### Error Response
```json
{
    "success": false,
    "message": "Error message",
    "error": "Detailed error information"
}
```

## HTTP Status Codes

- `200` - Success
- `400` - Bad Request (e.g., missing required search term)
- `404` - Resource not found
- `500` - Internal server error
- `401` - Unauthorized (invalid or missing token)

## Material Ordering

Materials are ordered by `display_order` (ascending) by default, with a secondary sort by `id` to ensure consistent ordering. This allows administrators to control the sequence in which materials are presented to users.

## Notes

1. All text searches are case-insensitive and use partial matching
2. The search endpoint searches both title and content fields
3. Materials include relationships to main and sub categories
4. Premium filtering allows access control based on user subscription
5. The display_order field controls the sequence of materials within categories
6. Pagination is optional but recommended for large datasets
7. Maximum items per page is limited to 100 for performance