# Modules Resource

## Description

Modules represent self-contained training content that users can complete. Each module contains metadata such as a title, description, categories, and a hosted content URL (typically on S3). Modules can be created and managed by Admins or Content Managers.

### Modules

Modules are the core content item assigned to users and grouped using categories and tags.

***

## Example

### Module:

```json
{
  "title": "Introduction to Cybersecurity",
  "description": "A beginner-friendly course on cybersecurity fundamentals.",
  "categories": ["cat123", "cat456"], // array of category IDs
  "estimatedDuration": 45,
  "isActive": true,
  "tags": ["security", "entry-level", "tech"],
  "createdAt": 1672444800000,
  "updatedAt": 1672444800000,
  "schemaVersion": 1,
  "_id": "mod123"
}
```

***

## Create Module – (!Admin or Content Manager!)

`POST /api/v1/modules`

**Example Request:**

```json
{
  "title": "Introduction to Cybersecurity",
  "description": "A beginner-friendly course on cybersecurity fundamentals.",
  "categories": ["cat123", "cat456"], // array of category IDs
  "estimatedDuration": 45,
  "isActive": true,
  "tags": ["security", "entry-level", "tech"],
  "createdAt": 1672444800000,
  "updatedAt": 1672444800000,
  "schemaVersion": 1,
  "_id": "mod123"
}
```

**Example Response (201 Created):**

```json
{
  "success": true,
  "message": "created module successfully.",
  "data": {
    "title": "Introduction to Cybersecurity",
    "description": "A beginner-friendly course on cybersecurity fundamentals.",
    "categories": ["cat123", "cat456"], // array of category IDs
    "estimatedDuration": 45,
    "isActive": true,
    "tags": ["security", "entry-level", "tech"],
    "createdAt": 1672444800000,
    "updatedAt": 1672444800000,
    "schemaVersion": 1,
    "_id": "mod123"
  }
}
```

***

## Get All Modules & Optionally Categorize

`GET /api/v1/modules`

With category filter:

`GET /api/v1/modules?categoryId={categoryID}`

**Example Response (200 OK):**

```json
{
  "success": true,
  "message": "retrieved modules successfully.",
  "data": [
    {
      "title": "Introduction to Cybersecurity",
      "description": "A beginner-friendly course on cybersecurity fundamentals.",
      "categories": ["cat123", "cat456"], // array of category IDs
      "estimatedDuration": 45,
      "isActive": true,
      "tags": ["security", "entry-level", "tech"],
      "createdAt": 1672444800000,
      "updatedAt": 1672444800000,
      "schemaVersion": 1,
      "_id": "mod123"
    }
  ]
}
```

Example Response (Filtered by Category)

```json
{
  "success": true,
  "message": "Modules retrieved for category abc successfully.",
  "data": [
    {
      "_id": "5",
      "title": "Bulltrout test",
      "description": "blah blah blah moer more more test test test",
      "estimatedDuration": 5,
      "isActive": true,
      "tags": [
        "Security"
      ],
      "createdAt": 1753900359452,
      "updatedAt": 1753900359452,
      "schemaVersion": 1,
      "categories": [
        "abc"
      ]
    }
  ]
}
```

***

## Get Module by ID

`GET /api/v1/modules/:id`

**Example Response (200 OK):**

```json
{
  "success": true,
  "message": "retrieved module successfully.",
  "data": {
    "title": "Introduction to Cybersecurity",
    "description": "A beginner-friendly course on cybersecurity fundamentals.",
    "categories": ["cat123", "cat456"], // array of category IDs
    "estimatedDuration": 45,
    "isActive": true,
    "tags": ["security", "entry-level", "tech"],
    "createdAt": 1672444800000,
    "updatedAt": 1672444800000,
    "schemaVersion": 1,
    "_id": "mod123"
  }
}
```

***

## Update Module – (!Admin or Content Manager!)

`PATCH /api/v1/modules/:id`

**Example Request:**

```json
{
  "title": "Cybersecurity Basics", // optional
  "isActive": false, // optional
  "tags": ["security", "updated"] // optional
}
```

**Example Response (200 OK):**

```json
{
  "success": true,
  "message": "updated module successfully.",
  "data": {
    "title": "Introduction to Cybersecurity",
    "description": "A beginner-friendly course on cybersecurity fundamentals.",
    "categories": ["cat123", "cat456"], // array of category IDs
    "estimatedDuration": 45,
    "isActive": true,
    "tags": ["security", "entry-level", "tech"],
    "createdAt": 1672444800000,
    "updatedAt": 1672444800000,
    "schemaVersion": 1,
    "_id": "mod123"
  }
}
```

***

## Delete Module – (!Admin Only!)

`DELETE /api/v1/modules/:id`

**Example Response (200 OK):**

```json
{
  "success": true,
  "message": "deleted module successfully."
}
```
