Skip to main content

​
1. API Purpose

The Activities API serves as the school’s social feed. It communicates events, achievements, and general announcements to parents, fostering engagement through a familiar interactive interface.

​
2. Endpoint Definition

MethodRouteAuthDescription
GET/parent-app/activities🔐 JWTView paginated activity feed
GET/teachers-app/activities🔐 JWTList school-wide activities
POST/teachers-app/activities🔐 JWTPost a new activity or announcement
PUT/teachers-app/activities/:id🔐 JWTEdit existing activity details
DELETE/teachers-app/activities/:id🔐 JWTSoft-delete an activity
GET/web-app/activities🔐 JWTAdmin: Comprehensive activity list

​
3. Authentication Flow

Standard Bearer JWT validation. Access is scoped by skole_id. Staff require specific RBAC permissions to create or delete posts.

​
4. Request Structure

​
GET /parent-app/activities

Query Parameters:
FieldTypeRequiredDescription
activity_typestringNoFilter by type (event/announcement).
student_idstringNoFilter by specific student.

​
GET /teachers-app/activities

Query Parameters:
FieldTypeRequiredDescription
skole_idstringYesSchool identifier.
activity_typestringNoFilter by type.
statusstringNoFilter by status (draft/published).

​
POST /teachers-app/activities

Request Body: 
{
  "skole_id": "SKL001",
  "title": "Annual Sports Day 2024",
  "description": "Join us for a day of sports and fun!",
  "activity_type": "event",
  "staff_id": 12,
  "student_id": null,
  "status": "published"
}

​
PUT /teachers-app/activities/:id

Request Body: 
{
  "title": "Updated Title",
  "status": "cancelled"
}

​
DELETE /teachers-app/activities/:id

URL Parameters:
FieldTypeDescription
idnumberID of the activity to delete.

​
GET /web-app/activities

Query Parameters:
FieldTypeRequiredDescription
skole_idstringYesSchool identifier.
pagenumberNoPage number (Default: 1).
limitnumberNoRecords per page (Default: 10).

​
5. Response Structure

​
Success: Parent Feed View (200 OK)

Route: GET /parent-app/activities 
{
  "success": true,
  "data": [
    {
      "id": 88,
      "title": "Annual Sports Day",
      "activity_type": "event",
      "created_at": "2024-03-10T09:00:00Z"
    }
  ]
}

​
Success: Teacher Activity List (200 OK)

Route: GET /teachers-app/activities 
{
  "success": true,
  "data": [
    {
      "id": 88,
      "title": "Sports Day",
      "status": "published",
      "author_id": 12
    }
  ]
}

​
Success: Activity Created (201 Created)

Route: POST /teachers-app/activities 
{
  "success": true,
  "message": "Activity published successfully",
  "data": {
    "id": 89,
    "title": "New Announcement"
  }
}

​
Success: Activity Updated (200 OK)

Route: PUT /teachers-app/activities/:id 
{
  "success": true,
  "message": "Update confirmed"
}

​
Success: Activity Deleted (200 OK)

Route: DELETE /teachers-app/activities/:id 
{
  "success": true,
  "message": "Activity soft-deleted"
}

​
Success: Admin Dashboard Feed (200 OK)

Route: GET /web-app/activities 
{
  "success": true,
  "data": {
    "records": [...],
    "pagination": { "total": 150, "page": 1 }
  }
}

​
6. Error Responses

HTTP CodeDescription
400Invalid skole_id or missing title
404Activity not found

​
7. Security Considerations

  • Soft Delete: deleted_status = 1 hides the item from all feeds without breaking database relations.
  • Tenant Isolation: Enforced via skole_id in JWT payload.

​
8. Token Usage

GET /parent-app/activity?page=2
Authorization: Bearer <TOKEN>

​
9. Token Refresh

N/A.

​
10. Logout / Session Invalidation

N/A.

​
11. Usage Example (cURL)

curl -H "Authorization: Bearer <TOKEN>" \
"http://localhost:3000/parent-app/activity?limit=5"

​
12. Notes / Special Behaviors

  • Engagement Integration: Comments and reactions for activities are handled by the separate Engagement API.
  • Targeting: Activities can be “School-wide” or targeted to a specific student_id.