Skip to main content

​
1. API Purpose

The Engagement API provides the interactive layer for the Skole platform. It allows parents and staff to acknowledge content (reactions) and ask clarifying questions (comments) on activities, diary entries, and notices.

​
2. Endpoint Definition

MethodRouteAuthDescription
POST/parent-app/engagement/comment🔐 JWTPost a new comment
GET/parent-app/engagement/comments/:type/:id🔐 JWTList comments for an entity
POST/parent-app/engagement/react🔐 JWTToggle a reaction (Like/Love)
GET/parent-app/engagement/reactions/:type/:id🔐 JWTGet counts and user’s reaction state

​
3. Authentication Flow

Standard JWT validation.
  • All engagement is tied to the parent_id or staff_id extracted from the token.
  • skole_id scoping ensures users only engage with content within their school.

​
4. Request Structure

​
POST /parent-app/engagement/comment

Request Body: 
{
  "entity_type": "activity",
  "entity_id": 88,
  "content": "Looking forward to the sports day!"
}

​
POST /parent-app/engagement/react

Request Body: 
{
  "entity_type": "diary",
  "entity_id": 501,
  "reaction_type": "love"
}

​
GET /parent-app/engagement/comments/:type/:id

URL Parameters:
FieldTypeDescription
typestringEntity type (activity, diary, write_to).
idnumberID of the specific entity.

​
GET /parent-app/engagement/reactions/:type/:id

URL Parameters:
FieldTypeDescription
typestringEntity type.
idnumberEntity ID.

​
5. Response Structure

​
Success: Comment Posted (201 Created)

Route: POST /parent-app/engagement/comment 
{
  "success": true,
  "message": "Comment added",
  "data": { "id": 1001, "content": "Looking forward to it!" }
}

​
Success: Comment List (200 OK)

Route: GET /parent-app/engagement/comments/:type/:id 
{
  "success": true,
  "data": [
    {
      "id": 1,
      "content": "Looking forward to it!",
      "author_name": "Ravi Kumar",
      "created_at": "2024-03-10T12:00:00Z"
    }
  ]
}

​
Success: Reaction Toggled (200 OK)

Route: POST /parent-app/engagement/react 
{
  "success": true,
  "message": "Reaction updated",
  "data": { "reaction_type": "love", "active": true }
}

​
Success: Reaction Stats (200 OK)

Route: GET /parent-app/engagement/reactions/:type/:id 
{
  "success": true,
  "data": {
    "love": 15,
    "thumbs_up": 22,
    "user_reaction": "love"
  }
}

​
6. Error Responses

HTTP CodeDescription
400Invalid entity_type (must be activity/diary/write_to/noticeboard)
404Target entity not found

​
7. Security Considerations

  • Unique Constraint: The database enforces a @@unique([entity_type, entity_id, parent_id, staff_id]) constraint to prevent duplicate reactions from the same user.
  • Toggle Logic: If the same reaction_type is sent twice, the reaction is removed (unlike standard social platforms).

​
8. Token Usage

POST /parent-app/engagement/react
Authorization: Bearer <TOKEN>

​
9. Token Refresh

N/A.

​
10. Logout / Session Invalidation

N/A.

​
11. Usage Example (cURL)

curl -X POST http://localhost:3000/parent-app/engagement/comment \
-H "Authorization: Bearer <TOKEN>" \
-d '{"entity_type": "diary", "entity_id": 501, "content": "Done!"}'

​
12. Notes / Special Behaviors

  • Cross-Module Linkage: The entity_type field allows one API to handle engagement for multiple modules without logic duplication.
  • Moderation: Deleted comments (deleted_status = 1) are filtered out at the service layer during listing.