16 KiB

Raw Permalink Blame History

API Documentation - Sistem Approval Artikel Dinamis

Overview

Dokumentasi ini menjelaskan API endpoints yang tersedia untuk sistem approval artikel dinamis. Sistem ini memungkinkan pembuatan workflow approval yang fleksibel dengan multiple level dan proses revisi.

Base URL

http://localhost:8800/api

Authentication

Semua endpoint memerlukan Bearer token authentication:

Authorization: Bearer <your_jwt_token>

1. Approval Workflows Management

1.1 Get All Workflows

GET /approval-workflows

Query Parameters:

page (optional): Page number (default: 1)
limit (optional): Items per page (default: 10)
search (optional): Search by workflow name
is_active (optional): Filter by active status (true/false)

Response:

{
  "success": true,
  "messages": ["Workflows retrieved successfully"],
  "data": [
    {
      "id": 1,
      "name": "Standard 3-Level Approval",
      "description": "Default workflow with 3 approval levels",
      "is_active": true,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z",
      "steps": [
        {
          "id": 1,
          "step_order": 1,
          "user_level_id": 3,
          "user_level": {
            "id": 3,
            "level_name": "Approver Level 3",
            "level_number": 3
          },
          "is_required": true,
          "can_skip": false
        }
      ]
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 10,
    "total": 5,
    "total_pages": 1
  }
}

1.2 Get Workflow by ID

GET /approval-workflows/{id}

Response:

{
  "success": true,
  "messages": ["Workflow retrieved successfully"],
  "data": {
    "id": 1,
    "name": "Standard 3-Level Approval",
    "description": "Default workflow with 3 approval levels",
    "is_active": true,
    "steps": [
      {
        "id": 1,
        "step_order": 1,
        "user_level_id": 3,
        "is_required": true,
        "can_skip": false
      }
    ]
  }
}

1.3 Create New Workflow

POST /approval-workflows

Request Body:

{
  "name": "Custom 2-Level Approval",
  "description": "Fast track approval for urgent articles",
  "steps": [
    {
      "stepOrder": 1,
      "userLevelId": 2,
      "isRequired": true,
      "canSkip": false
    },
    {
      "stepOrder": 2,
      "userLevelId": 1,
      "isRequired": true,
      "canSkip": false
    }
  ]
}

Validation Rules:

name: Required, max 255 characters
steps: Required, minimum 1 step
stepOrder: Must be sequential starting from 1
userLevelId: Must exist in user_levels table

Response:

{
  "success": true,
  "messages": ["Workflow created successfully"],
  "data": {
    "id": 5,
    "name": "Custom 2-Level Approval",
    "description": "Fast track approval for urgent articles",
    "is_active": true,
    "created_at": "2024-01-15T14:30:00Z"
  }
}

1.4 Update Workflow

PUT /approval-workflows/{id}

Request Body:

{
  "name": "Updated Workflow Name",
  "description": "Updated description",
  "is_active": true
}

1.5 Delete Workflow

DELETE /approval-workflows/{id}

Note: Workflow can only be deleted if no articles are currently using it.

2. Article Approval Management

2.1 Submit Article for Approval

POST /articles/{id}/submit-approval

Request Body:

{
  "workflowId": 2
}

Response:

{
  "success": true,
  "messages": ["Article submitted for approval successfully"],
  "data": {
    "id": 15,
    "article_id": 123,
    "workflow_id": 2,
    "current_step": 1,
    "status_id": 1,
    "created_at": "2024-01-15T15:00:00Z"
  }
}

2.2 Approve Current Step

POST /articles/{id}/approve

Request Body:

{
  "message": "Article content is excellent, approved for next level"
}

Response:

{
  "success": true,
  "messages": ["Article approved successfully"],
  "data": {
    "next_step": 2,
    "status": "moved_to_next_level"
  }
}

2.3 Reject Article

POST /articles/{id}/reject

Request Body:

{
  "message": "Article does not meet quality standards"
}

Response:

{
  "success": true,
  "messages": ["Article rejected successfully"]
}

2.4 Request Revision

POST /articles/{id}/request-revision

Request Body:

{
  "message": "Please fix grammar issues in paragraph 3 and add more references"
}

Response:

{
  "success": true,
  "messages": ["Revision requested successfully"]
}

2.5 Resubmit After Revision

POST /articles/{id}/resubmit

Request Body:

{
  "message": "Fixed all requested issues"
}

Response:

{
  "success": true,
  "messages": ["Article resubmitted successfully"],
  "data": {
    "current_step": 1,
    "status": "back_in_approval_flow"
  }
}

3. Approval Dashboard

3.1 Get Pending Approvals for Current User

GET /approvals/pending

Query Parameters:

page (optional): Page number (default: 1)
limit (optional): Items per page (default: 10, max: 50)
priority (optional): Filter by priority (high, medium, low)
category_id (optional): Filter by article category
search (optional): Search in article title or author name
date_from (optional): Filter articles submitted from date (YYYY-MM-DD)
date_to (optional): Filter articles submitted to date (YYYY-MM-DD)
sort_by (optional): Sort by field (waiting_time, created_at, title, priority)
sort_order (optional): Sort order (asc, desc) - default: desc
workflow_id (optional): Filter by specific workflow

Response:

{
  "success": true,
  "messages": ["Pending approvals retrieved successfully"],
  "data": [
    {
      "id": 15,
      "article": {
        "id": 123,
        "title": "Understanding Machine Learning",
        "excerpt": "This article explores the fundamentals of machine learning...",
        "author": {
          "id": 45,
          "name": "John Doe",
          "email": "john@example.com",
          "profile_picture": "https://example.com/avatar.jpg"
        },
        "category": {
          "id": 5,
          "name": "Technology",
          "color": "#3B82F6"
        },
        "word_count": 1250,
        "estimated_read_time": "5 min",
        "created_at": "2024-01-15T10:00:00Z",
        "submitted_at": "2024-01-15T14:30:00Z"
      },
      "workflow": {
        "id": 2,
        "name": "Standard 3-Level Approval",
        "total_steps": 3
      },
      "current_step": 2,
      "my_step_order": 2,
      "waiting_since": "2024-01-15T14:30:00Z",
      "waiting_duration_hours": 6.5,
      "priority": "medium",
      "previous_approvals": [
        {
          "step_order": 1,
          "approver_name": "Jane Smith",
          "approved_at": "2024-01-15T14:30:00Z",
          "message": "Content looks good"
        }
      ],
      "urgency_score": 7.5,
      "can_approve": true,
      "can_reject": true,
      "can_request_revision": true
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 10,
    "total": 5,
    "total_pages": 1
  },
  "summary": {
    "total_pending": 5,
    "high_priority": 2,
    "medium_priority": 2,
    "low_priority": 1,
    "overdue_count": 1,
    "avg_waiting_hours": 8.2
  }
}

3.2 Get Approval History for Article

GET /articles/{id}/approval-history

Response:

{
  "success": true,
  "messages": ["Approval history retrieved successfully"],
  "data": {
    "article_id": 123,
    "workflow": {
      "id": 2,
      "name": "Standard 3-Level Approval"
    },
    "current_step": 2,
    "status": "in_progress",
    "history": [
      {
        "id": 1,
        "step_order": 1,
        "action": "approved",
        "message": "Good content, approved",
        "approver": {
          "id": 67,
          "name": "Jane Smith",
          "level": "Approver Level 3"
        },
        "approved_at": "2024-01-15T14:30:00Z"
      }
    ]
  }
}

3.3 Get My Approval Statistics

GET /approvals/my-stats

Response:

{
  "success": true,
  "messages": ["Statistics retrieved successfully"],
  "data": {
    "pending_count": 5,
    "overdue_count": 1,
    "approved_today": 3,
    "approved_this_week": 15,
    "approved_this_month": 45,
    "rejected_this_month": 2,
    "revision_requests_this_month": 8,
    "average_approval_time_hours": 4.5,
    "fastest_approval_minutes": 15,
    "slowest_approval_hours": 48,
    "approval_rate_percentage": 85.2,
    "categories_breakdown": [
      {
        "category_name": "Technology",
        "pending": 2,
        "approved_this_month": 12
      },
      {
        "category_name": "Health",
        "pending": 3,
        "approved_this_month": 8
      }
    ]
  }
}

3.4 Get Articles Requiring My Approval (Detailed View)

GET /approvals/my-queue

Query Parameters:

Same as /approvals/pending but specifically filtered for current user's level
include_preview (optional): Include article content preview (true/false)
urgency_only (optional): Show only urgent articles (true/false)

Response:

{
  "success": true,
  "messages": ["My approval queue retrieved successfully"],
  "data": [
    {
      "id": 15,
      "article": {
        "id": 123,
        "title": "Understanding Machine Learning",
        "content_preview": "Machine learning is a subset of artificial intelligence that enables computers to learn and improve from experience without being explicitly programmed...",
        "full_content_available": true,
        "author": {
          "id": 45,
          "name": "John Doe",
          "reputation_score": 8.5,
          "articles_published": 25,
          "approval_success_rate": 92.3
        },
        "submission_notes": "This is an updated version based on previous feedback",
        "tags": ["AI", "Technology", "Education"],
        "seo_score": 85,
        "readability_score": "Good"
      },
      "approval_context": {
        "my_role_in_workflow": "Senior Editor Review",
        "step_description": "Review content quality and technical accuracy",
        "expected_action": "Approve or request technical revisions",
        "deadline": "2024-01-16T18:00:00Z",
        "is_overdue": false,
        "escalation_available": true
      },
      "workflow_progress": {
        "completed_steps": 1,
        "total_steps": 3,
        "progress_percentage": 33.3,
        "next_approver": "Chief Editor"
      }
    }
  ]
}

3.5 Get Approval Workload Distribution

GET /approvals/workload

Response:

{
  "success": true,
  "messages": ["Workload distribution retrieved successfully"],
  "data": {
    "my_level": {
      "level_name": "Senior Editor",
      "level_number": 2,
      "pending_articles": 5,
      "avg_daily_approvals": 8.5
    },
    "team_comparison": [
      {
        "approver_name": "Jane Smith",
        "level_name": "Senior Editor",
        "pending_articles": 3,
        "avg_response_time_hours": 2.5
      },
      {
        "approver_name": "Mike Johnson",
        "level_name": "Senior Editor",
        "pending_articles": 7,
        "avg_response_time_hours": 4.2
      }
    ],
    "bottlenecks": [
      {
        "level_name": "Chief Editor",
        "pending_count": 12,
        "avg_waiting_time_hours": 18.5,
        "is_bottleneck": true
      }
    ]
  }
}

3.6 Bulk Approval Actions

POST /approvals/bulk-action

Request Body:

{
  "article_ids": [123, 124, 125],
  "action": "approve",
  "message": "Bulk approval for similar content type",
  "apply_to_similar": false
}

Response:

{
  "success": true,
  "messages": ["Bulk action completed successfully"],
  "data": {
    "processed_count": 3,
    "successful_count": 3,
    "failed_count": 0,
    "results": [
      {
        "article_id": 123,
        "status": "success",
        "next_step": 3
      },
      {
        "article_id": 124,
        "status": "success",
        "next_step": 3
      },
      {
        "article_id": 125,
        "status": "success",
        "next_step": "published"
      }
    ]
  }
}

4. User Level Management

4.1 Get Available User Levels

GET /user-levels

Response:

{
  "success": true,
  "messages": ["User levels retrieved successfully"],
  "data": [
    {
      "id": 1,
      "level_name": "Chief Editor",
      "level_number": 1,
      "parent_level_id": null,
      "is_approval_active": true
    },
    {
      "id": 2,
      "level_name": "Senior Editor",
      "level_number": 2,
      "parent_level_id": 1,
      "is_approval_active": true
    },
    {
      "id": 3,
      "level_name": "Junior Editor",
      "level_number": 3,
      "parent_level_id": 2,
      "is_approval_active": true
    }
  ]
}

5. Error Responses

5.1 Validation Error (400)

{
  "success": false,
  "messages": ["Validation failed"],
  "errors": {
    "name": ["Name is required"],
    "steps": ["At least one step is required"]
  }
}

5.2 Unauthorized (401)

{
  "success": false,
  "messages": ["Unauthorized access"]
}

5.3 Forbidden (403)

{
  "success": false,
  "messages": ["You don't have permission to approve this article"]
}

5.4 Not Found (404)

{
  "success": false,
  "messages": ["Article not found"]
}

5.5 Business Logic Error (422)

{
  "success": false,
  "messages": ["Article already has active approval flow"]
}

5.6 Internal Server Error (500)

{
  "success": false,
  "messages": ["Internal server error occurred"]
}

6. Webhook Events (Optional)

Sistem dapat mengirim webhook notifications untuk event-event penting:

6.1 Article Submitted for Approval

{
  "event": "article.submitted_for_approval",
  "timestamp": "2024-01-15T15:00:00Z",
  "data": {
    "article_id": 123,
    "workflow_id": 2,
    "submitted_by": {
      "id": 45,
      "name": "John Doe"
    },
    "next_approver_level": 3
  }
}

6.2 Article Approved

{
  "event": "article.approved",
  "timestamp": "2024-01-15T16:00:00Z",
  "data": {
    "article_id": 123,
    "approved_by": {
      "id": 67,
      "name": "Jane Smith",
      "level": 3
    },
    "current_step": 2,
    "is_final_approval": false
  }
}

6.3 Article Published

{
  "event": "article.published",
  "timestamp": "2024-01-15T17:00:00Z",
  "data": {
    "article_id": 123,
    "final_approver": {
      "id": 89,
      "name": "Chief Editor",
      "level": 1
    },
    "total_approval_time_hours": 6.5
  }
}

6.4 Revision Requested

{
  "event": "article.revision_requested",
  "timestamp": "2024-01-15T16:30:00Z",
  "data": {
    "article_id": 123,
    "requested_by": {
      "id": 67,
      "name": "Jane Smith",
      "level": 2
    },
    "message": "Please fix grammar issues",
    "author": {
      "id": 45,
      "name": "John Doe"
    }
  }
}

7. Rate Limiting

API menggunakan rate limiting untuk mencegah abuse:

General endpoints: 100 requests per minute per user
Approval actions: 50 requests per minute per user
Workflow management: 20 requests per minute per user

8. Pagination

Semua endpoint yang mengembalikan list menggunakan pagination:

Default limit: 10
Maximum limit: 100
Default page: 1

9. Filtering dan Sorting

Beberapa endpoint mendukung filtering dan sorting:

Query Parameters untuk Filtering:

status: Filter by status
user_level: Filter by user level
date_from: Filter from date (YYYY-MM-DD)
date_to: Filter to date (YYYY-MM-DD)
search: Search in title/content

Query Parameters untuk Sorting:

sort_by: Field to sort by (created_at, updated_at, title, etc.)
sort_order: asc atau desc (default: desc)

Contoh:

GET /articles?status=pending&sort_by=created_at&sort_order=asc&page=1&limit=20

10. Bulk Operations

10.1 Bulk Approve Articles

POST /articles/bulk-approve

Request Body:

{
  "article_ids": [123, 124, 125],
  "message": "Bulk approval for similar articles"
}

10.2 Bulk Assign Workflow

POST /articles/bulk-assign-workflow

Request Body:

{
  "article_ids": [123, 124, 125],
  "workflow_id": 2
}

Dokumentasi API ini memberikan panduan lengkap untuk mengintegrasikan sistem approval artikel dinamis dengan frontend atau sistem eksternal lainnya.

16 KiB Raw Permalink Blame History

API Documentation - Sistem Approval Artikel Dinamis

Overview

Base URL

Authentication

1. Approval Workflows Management

1.1 Get All Workflows

1.2 Get Workflow by ID

1.3 Create New Workflow

1.4 Update Workflow

1.5 Delete Workflow

2. Article Approval Management

2.1 Submit Article for Approval

2.2 Approve Current Step

2.3 Reject Article

2.4 Request Revision

2.5 Resubmit After Revision

3. Approval Dashboard

3.1 Get Pending Approvals for Current User

3.2 Get Approval History for Article

3.3 Get My Approval Statistics

3.4 Get Articles Requiring My Approval (Detailed View)

3.5 Get Approval Workload Distribution

3.6 Bulk Approval Actions

4. User Level Management

4.1 Get Available User Levels

5. Error Responses

5.1 Validation Error (400)

5.2 Unauthorized (401)

5.3 Forbidden (403)

5.4 Not Found (404)

5.5 Business Logic Error (422)

5.6 Internal Server Error (500)

6. Webhook Events (Optional)

6.1 Article Submitted for Approval

6.2 Article Approved

6.3 Article Published

6.4 Revision Requested

7. Rate Limiting

8. Pagination

9. Filtering dan Sorting

Query Parameters untuk Filtering:

Query Parameters untuk Sorting:

10. Bulk Operations

10.1 Bulk Approve Articles

10.2 Bulk Assign Workflow

16 KiB

Raw Permalink Blame History