qudoco-be/docs/notes/api-endpoints-documentation.md

# API Endpoints Documentation

## Overview
Dokumentasi lengkap untuk semua API endpoint yang tersedia di sistem dynamic article approval. Dokumen ini mencakup endpoint untuk approval workflows, article approval flows, approval workflow steps, article approval step logs, dan client approval settings.

---

## 📋 Table of Contents
1. [Approval Workflows](#approval-workflows)
2. [Article Approval Flows](#article-approval-flows)
3. [Approval Workflow Steps](#approval-workflow-steps)
4. [Article Approval Step Logs](#article-approval-step-logs)
5. [Client Approval Settings](#client-approval-settings)
6. [Articles (Enhanced)](#articles-enhanced)

---

## 🔄 Approval Workflows

**Base Path:** `/approval-workflows`

### Endpoint List

| Endpoint | Method | Purpose | Description |
|----------|--------|---------|-------------|
| `/approval-workflows` | GET | Get All Workflows | Retrieve all approval workflows for the client |
| `/approval-workflows` | POST | Create Workflow | Create a new approval workflow |
| `/approval-workflows/:id` | GET | Get Workflow by ID | Get specific workflow details |
| `/approval-workflows/:id` | PUT | Update Workflow | Update existing workflow |
| `/approval-workflows/:id` | DELETE | Delete Workflow | Delete workflow (soft delete) |
| `/approval-workflows/default` | GET | Get Default Workflow | Get the default workflow for the client |
| `/approval-workflows/:id/with-steps` | GET | Get Workflow with Steps | Get workflow including all its approval steps |
| `/approval-workflows/:id/activate` | POST | Activate Workflow | Activate a workflow |
| `/approval-workflows/:id/deactivate` | POST | Deactivate Workflow | Deactivate a workflow |

### Request/Response Examples

#### Create Workflow
```json
POST /approval-workflows
{
    "name": "3-Level Editorial Review",
    "description": "Standard editorial workflow with 3 approval levels",
    "is_default": true,
    "is_active": true,
    "requires_approval": true,
    "auto_publish": false,
    "steps": [
        {
            "step_order": 1,
            "step_name": "Editor Review",
            "required_user_level_id": 2,
            "estimated_days": 1
        },
        {
            "step_order": 2,
            "step_name": "Senior Editor Review",
            "required_user_level_id": 3,
            "estimated_days": 2
        },
        {
            "step_order": 3,
            "step_name": "Editor in Chief",
            "required_user_level_id": 4,
            "estimated_days": 1
        }
    ]
}
```

---

## 📝 Article Approval Flows

**Base Path:** `/article-approval-flows`

### Endpoint List

| Endpoint | Method | Purpose | Description |
|----------|--------|---------|-------------|
| `/article-approval-flows` | GET | Get All Flows | Retrieve all article approval flows |
| `/article-approval-flows` | POST | Create Flow | Create new approval flow for article |
| `/article-approval-flows/:id` | GET | Get Flow by ID | Get specific approval flow details |
| `/article-approval-flows/:id` | PUT | Update Flow | Update approval flow |
| `/article-approval-flows/:id` | DELETE | Delete Flow | Delete approval flow |
| `/article-approval-flows/my-queue` | GET | Get My Queue | Get articles pending approval for current user |
| `/article-approval-flows/submit` | POST | Submit for Approval | Submit article for approval process |
| `/article-approval-flows/:id/approve` | POST | Approve Step | Approve current approval step |
| `/article-approval-flows/:id/reject` | POST | Reject Article | Reject article and return to author |
| `/article-approval-flows/:id/request-revision` | POST | Request Revision | Request revision from author |
| `/article-approval-flows/:id/resubmit` | POST | Resubmit After Revision | Resubmit article after revision |
| `/article-approval-flows/:id/status` | GET | Get Flow Status | Get current status of approval flow |

### Request/Response Examples

#### Submit for Approval
```json
POST /article-approval-flows/submit
{
    "article_id": 123,
    "workflow_id": 1,
    "message": "Ready for editorial review"
}
```

#### Approve Step
```json
POST /article-approval-flows/456/approve
{
    "message": "Content approved, moving to next level",
    "comments": "Good quality content, minor formatting suggestions"
}
```

#### Reject Article
```json
POST /article-approval-flows/456/reject
{
    "reason": "Content does not meet editorial standards",
    "feedback": "Please revise the introduction and add more supporting evidence",
    "return_to_step": 1
}
```

---

## ⚙️ Approval Workflow Steps

**Base Path:** `/approval-workflow-steps`

### Endpoint List

| Endpoint | Method | Purpose | Description |
|----------|--------|---------|-------------|
| `/approval-workflow-steps` | GET | Get All Steps | Retrieve all workflow steps |
| `/approval-workflow-steps` | POST | Create Step | Create new workflow step |
| `/approval-workflow-steps/:id` | GET | Get Step by ID | Get specific step details |
| `/approval-workflow-steps/:id` | PUT | Update Step | Update existing step |
| `/approval-workflow-steps/:id` | DELETE | Delete Step | Delete workflow step |
| `/approval-workflow-steps/workflow/:workflow_id` | GET | Get Steps by Workflow | Get all steps for specific workflow |
| `/approval-workflow-steps/:id/reorder` | PUT | Reorder Step | Change step order in workflow |
| `/approval-workflow-steps/:id/activate` | POST | Activate Step | Activate specific step |
| `/approval-workflow-steps/:id/deactivate` | POST | Deactivate Step | Deactivate specific step |

### Request/Response Examples

#### Create Workflow Step
```json
POST /approval-workflow-steps
{
    "workflow_id": 1,
    "step_order": 1,
    "step_name": "Initial Review",
    "step_description": "First level content review",
    "required_user_level_id": 2,
    "estimated_days": 1,
    "is_required": true,
    "can_skip": false,
    "auto_approve_after_days": null
}
```

#### Reorder Step
```json
PUT /approval-workflow-steps/5/reorder
{
    "new_order": 2
}
```

---

## 📊 Article Approval Step Logs

**Base Path:** `/article-approval-step-logs`

### Endpoint List

| Endpoint | Method | Purpose | Description |
|----------|--------|---------|-------------|
| `/article-approval-step-logs` | GET | Get All Logs | Retrieve all approval step logs |
| `/article-approval-step-logs` | POST | Create Log | Create new approval step log |
| `/article-approval-step-logs/:id` | GET | Get Log by ID | Get specific log details |
| `/article-approval-step-logs/:id` | PUT | Update Log | Update existing log |
| `/article-approval-step-logs/:id` | DELETE | Delete Log | Delete approval step log |
| `/article-approval-step-logs/flow/:flow_id` | GET | Get Logs by Flow | Get all logs for specific approval flow |
| `/article-approval-step-logs/article/:article_id` | GET | Get Logs by Article | Get all logs for specific article |
| `/article-approval-step-logs/user/:user_id` | GET | Get Logs by User | Get all logs created by specific user |
| `/article-approval-step-logs/step/:step_id` | GET | Get Logs by Step | Get all logs for specific workflow step |

### Request/Response Examples

#### Create Approval Step Log
```json
POST /article-approval-step-logs
{
    "approval_flow_id": 123,
    "workflow_step_id": 5,
    "action": "approved",
    "action_by_user_id": 45,
    "action_date": "2024-01-15T10:30:00Z",
    "comments": "Content meets quality standards",
    "metadata": {
        "review_time_minutes": 15,
        "revision_count": 0
    }
}
```

#### Get Logs by Flow
```json
GET /article-approval-step-logs/flow/123?page=1&limit=10
```

---

## ⚙️ Client Approval Settings

**Base Path:** `/client-approval-settings`

### Endpoint List

| Endpoint | Method | Purpose | Description |
|----------|--------|---------|-------------|
| `/client-approval-settings` | GET | Get Settings | Get current client approval settings |
| `/client-approval-settings` | PUT | Update Settings | Update client approval settings |
| `/client-approval-settings/toggle` | POST | Toggle Approval | Quick toggle approval on/off |
| `/client-approval-settings/enable` | POST | Enable Approval | Enable approval system with transition |
| `/client-approval-settings/disable` | POST | Disable Approval | Disable approval with auto-publish |
| `/client-approval-settings/default-workflow` | POST | Set Default Workflow | Set default workflow for client |
| `/client-approval-settings/exempt-users/add/{user_id}` | POST | Add Exempt User | Add user to approval exemption |
| `/client-approval-settings/exempt-users/remove/{user_id}` | POST | Remove Exempt User | Remove user from exemption |
| `/client-approval-settings/exempt-roles/add/{role_id}` | POST | Add Exempt Role | Add role to approval exemption |
| `/client-approval-settings/exempt-roles/remove/{role_id}` | POST | Remove Exempt Role | Remove role from exemption |
| `/client-approval-settings/exempt-categories/add/{category_id}` | POST | Add Exempt Category | Add category to exemption |
| `/client-approval-settings/exempt-categories/remove/{category_id}` | POST | Remove Exempt Category | Remove category from exemption |

### Request/Response Examples

#### Toggle Approval System
```json
POST /client-approval-settings/toggle
{
    "requires_approval": false
}
```

#### Enable Approval with Transition
```json
POST /client-approval-settings/enable
{
    "default_workflow_id": 1,
    "reason": "Implementing content quality control"
}
```

#### Disable Approval with Auto-Publish
```json
POST /client-approval-settings/disable
{
    "reason": "Streamlining content publishing for breaking news",
    "handle_action": "auto_approve"
}
```

#### Update Settings
```json
PUT /client-approval-settings
{
    "requires_approval": true,
    "auto_publish_articles": false,
    "default_workflow_id": 1,
    "approval_exempt_users": [10, 15, 20],
    "approval_exempt_roles": [2, 3],
    "approval_exempt_categories": [5],
    "require_approval_for": ["news", "opinion"],
    "skip_approval_for": ["announcement", "update"]
}
```

---

## 📰 Articles (Enhanced)

**Base Path:** `/articles`

### New Dynamic Approval Endpoints

| Endpoint | Method | Purpose | Description |
|----------|--------|---------|-------------|
| `/articles/:id/submit-approval` | POST | Submit for Approval | Submit article for approval process |
| `/articles/:id/approval-status` | GET | Get Approval Status | Get current approval status and progress |
| `/articles/pending-approval` | GET | Get Pending Approvals | Get articles pending approval for user level |

### Request/Response Examples

#### Submit Article for Approval
```json
POST /articles/123/submit-approval
{
    "workflow_id": 1,
    "message": "Ready for editorial review"
}
```

#### Get Approval Status
```json
GET /articles/123/approval-status
```

**Response:**
```json
{
    "success": true,
    "data": {
        "article_id": 123,
        "current_status": "pending_approval",
        "current_step": 1,
        "total_steps": 3,
        "workflow_name": "3-Level Editorial Review",
        "current_step_name": "Editor Review",
        "next_step_name": "Senior Editor Review",
        "estimated_completion": "2024-01-18T10:30:00Z",
        "approval_progress": {
            "completed_steps": 0,
            "total_steps": 3,
            "percentage": 0
        },
        "pending_approver": {
            "user_level_id": 2,
            "user_level_name": "Editor",
            "estimated_days": 1
        }
    }
}
```

#### Get Pending Approvals
```json
GET /articles/pending-approval?page=1&limit=10
```

**Response:**
```json
{
    "success": true,
    "data": [
        {
            "article_id": 123,
            "title": "Breaking News Article",
            "category_name": "News",
            "author_name": "John Doe",
            "submitted_at": "2024-01-15T09:00:00Z",
            "current_step": 1,
            "workflow_name": "3-Level Editorial Review",
            "priority": "high",
            "estimated_time": "2 days",
            "article_thumbnail": "https://example.com/thumb.jpg"
        }
    ],
    "pagination": {
        "page": 1,
        "limit": 10,
        "total": 25,
        "total_pages": 3
    }
}
```

---

## 🔐 Authentication & Authorization

### Headers Required
```
X-Client-Key: {client_key}
Authorization: Bearer {jwt_token}
```

### Client ID Context
Semua endpoint menggunakan `X-Client-Key` header untuk mengidentifikasi client dan memastikan data isolation.

---

## 📊 Response Format

### Success Response
```json
{
    "success": true,
    "messages": ["Operation completed successfully"],
    "data": { ... },
    "pagination": { ... } // if applicable
}
```

### Error Response
```json
{
    "success": false,
    "messages": ["Error message"],
    "error": "BAD_REQUEST",
    "data": null
}
```

---

## 🚀 Usage Examples

### Complete Workflow Creation
```bash
# 1. Create approval workflow
POST /approval-workflows
{
    "name": "Editorial Review",
    "description": "Standard editorial workflow",
    "is_default": true,
    "requires_approval": true,
    "auto_publish": false
}

# 2. Create workflow steps
POST /approval-workflow-steps
{
    "workflow_id": 1,
    "step_order": 1,
    "step_name": "Editor Review",
    "required_user_level_id": 2
}

# 3. Submit article for approval
POST /articles/123/submit-approval
{
    "workflow_id": 1,
    "message": "Ready for review"
}

# 4. Approve first step
POST /article-approval-flows/456/approve
{
    "message": "Content approved"
}
```

### Dynamic Approval Toggle
```bash
# Disable approval temporarily
POST /client-approval-settings/disable
{
    "reason": "Breaking news mode",
    "handle_action": "auto_approve"
}

# Re-enable approval
POST /client-approval-settings/enable
{
    "default_workflow_id": 1,
    "reason": "Returning to normal process"
}
```

---

## 📝 Notes

### Important Considerations
1. **Client Isolation**: Semua endpoint menggunakan client ID untuk data isolation
2. **Workflow Flexibility**: Workflow dapat dikonfigurasi dengan unlimited steps
3. **Dynamic Toggle**: Approval system dapat di-enable/disable secara real-time
4. **Audit Trail**: Semua approval actions dicatat untuk compliance
5. **Auto-Publish**: Artikel dapat di-auto-publish ketika approval di-disable

### Performance Notes
- Pagination tersedia untuk endpoint yang return banyak data
- Database queries dioptimasi dengan proper indexing
- Caching dapat diimplementasikan untuk frequently accessed data

### Security Features
- JWT token authentication
- Client-level data isolation
- Role-based access control
- Audit logging untuk semua actions

---

## 🔄 Version History

| Version | Date | Changes |
|---------|------|---------|
| 1.0.0 | 2024-01-15 | Initial API documentation |
| 1.1.0 | 2024-01-15 | Added dynamic approval toggle endpoints |
| 1.2.0 | 2024-01-15 | Enhanced with client approval settings |

---

*Dokumentasi ini akan diupdate secara berkala sesuai dengan perkembangan sistem.*