Approval APIs

Endpoints for requesting approval, approving, and rejecting content for publication.

Base URL: https://ycwadelaide.adenmgb.com

Authentication: All endpoints require Authorization: Bearer <token> header.

Overview

The approval system enforces a workflow where:

1. Content creators create content as drafts
2. Content creators request approval for publication
3. Approvers review and approve or reject content
4. Approved content is automatically published
5. Rejected content returns to draft status with optional feedback

Supported Content Types:

• actions - YCW Actions
• events - Events
• news - News Articles
• newsletters - Newsletters

Approval Status Values:

• draft - Initial state, not submitted for approval
• pending - Approval requested, awaiting review
• approved - Approved and ready to publish
• rejected - Rejected, needs changes

POST /api/staff/approval/request

Request approval for content to be published.

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "contentType": "actions",
  "contentId": 5
}

Success Response (200 OK):

{
  "success": true
}

What Happens:

1. Content approval_status is set to pending
2. approval_requested_at timestamp is set
3. approval_requested_by is set to requesting user ID
4. Notifications are sent to all approvers
5. Audit log entry is created

Error Responses:

• 400 Bad Request - Missing required fields
• 401 Unauthorized - Not authenticated
• 404 Not Found - Content not found
• 500 Internal Server Error - Failed to request approval

POST /api/staff/approval/approve

Approve content for publication. This automatically publishes the content.

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "contentType": "actions",
  "contentId": 5
}

Success Response (200 OK):

{
  "success": true
}

What Happens:

1. Content approval_status is set to approved
2. approved_at timestamp is set
3. approved_by is set to approver user ID
4. Content published status is set to 1 (published)
5. Notification is sent to the requester
6. Audit log entry is created

Error Responses:

• 400 Bad Request - Missing required fields
• 401 Unauthorized - Not authenticated
• 403 Forbidden - User doesn't have permission to approve
• 404 Not Found - Content not found
• 500 Internal Server Error - Failed to approve

Notes:

• User must have approval permissions for the content type
• Content is automatically published when approved
• Only one approval is needed

POST /api/staff/approval/reject

Reject content and return it to draft status.

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "contentType": "actions",
  "contentId": 5,
  "reason": "Needs more details about location and timing"
}

Success Response (200 OK):

{
  "success": true
}

What Happens:

1. Content approval_status is set to rejected
2. rejected_at timestamp is set
3. rejected_by is set to rejector user ID
4. rejection_reason is stored (if provided)
5. Content published status is set to 0 (unpublished)
6. Notification is sent to the requester with rejection reason
7. Audit log entry is created

Error Responses:

• 400 Bad Request - Missing required fields
• 401 Unauthorized - Not authenticated
• 403 Forbidden - User doesn't have permission to reject
• 404 Not Found - Content not found
• 500 Internal Server Error - Failed to reject

Notes:

• Rejection reason is optional but recommended
• Content is automatically unpublished when rejected

GET /api/staff/approval-config

Get approval configuration (which roles can approve which content types).

Headers:

Authorization: Bearer <token>

Success Response (200 OK):

[
  {
    "id": 1,
    "contentType": "actions",
    "roleId": 2,
    "roleName": "Editor"
  }
]

Notes:

• Only users with admin permissions can view/modify approval config
• Used to determine who receives approval request notifications

POST /api/staff/approval-config

Create approval configuration (assign approval permissions to roles).

Headers:

Authorization: Bearer <token>
Content-Type: application/json

Request Body:

{
  "contentType": "actions",
  "roleId": 2
}

Success Response (200 OK):

{
  "success": true,
  "id": 1
}

Notes:

• Requires admin permissions
• Users with the specified role will receive approval request notifications

DELETE /api/staff/approval-config/:id

Delete approval configuration.

Headers:

Authorization: Bearer <token>

URL Parameters:

• id - Configuration ID

Success Response (200 OK):

{
  "success": true
}

Notes:

• Requires admin permissions
• Removes approval permissions for a role/content type combination

Workflow Example

1. Create Content (Draft)
   POST /api/staff/actions
   { "title": "New Action", "published": false }
   // Returns: { "id": 5, "approvalStatus": "draft" }
   

2. Request Approval
   POST /api/staff/approval/request
   { "contentType": "actions", "contentId": 5 }
   // Content status: "pending"
   // Approvers receive notifications
   

3. Approver Reviews and Approves
   POST /api/staff/approval/approve
   { "contentType": "actions", "contentId": 5 }
   // Content status: "approved"
   // Content published: true
   // Requester receives notification
   

Related APIs

• Notifications API - View approval notifications
• Content APIs - Manage content