Skip to main content

​
1. API Purpose

The Academic Calendar API provides a single source of truth for the school’s annual events. It helps parents and staff stay aligned on important dates, reducing scheduling conflicts and missed milestones.

​
2. Endpoint Definition

MethodRouteAuthDescription
GET/parent-app/academic-events🔐 JWTView upcoming academic events
GET/teachers-app/academic-calendar🔐 JWTStaff: View all scheduled events
POST/teachers-app/academic-calendar🔐 JWTStaff: Create a new academic event
PUT/teachers-app/academic-calendar/:id🔐 JWTStaff: Update event details
DELETE/teachers-app/academic-calendar/:id🔐 JWTStaff: Soft-delete an event
GET/web-app/academic-calendar🔐 JWTAdmin: Comprehensive event list
POST/web-app/academic-calendar🔐 JWTAdmin: Create academic event
POST/web-app/bulk-import-academic-calendar-json🔐 JWTAdmin: Bulk import from JSON

​
3. Authentication Flow

Standard Bearer JWT validation. Access is school-specific (skole_id). Staff require specific RBAC permission to manage the calendar.

​
4. Request Structure

​
GET /parent-app/academic-events

Headers: 
Authorization: Bearer <JWT_TOKEN>

​
GET /web-app/academic-calendar

Query Parameters:
FieldTypeRequiredDescription
skole_idstringYesSchool identifier.
event_typestringNoFilter by type (holiday/event).
from_datestringNoStart date filter (YYYY-MM-DD).
to_datestringNoEnd date filter (YYYY-MM-DD).

​
POST /web-app/academic-calendar

Request Body: 
{
  "skole_id": "SKL001",
  "title": "Annual Day Celebration",
  "description": "Grand celebration in the school auditorium.",
  "event_type": "event",
  "event_from_date": "2024-12-20T00:00:00Z",
  "event_to_date": "2024-12-20T00:00:00Z",
  "event_time": "10:00 AM"
}

​
PUT /teachers-app/academic-calendar/:id

Request Body: 
{
  "title": "Updated Event Title",
  "event_time": "11:00 AM"
}

​
DELETE /teachers-app/academic-calendar/:id

URL Parameters:
FieldTypeDescription
idnumberID of the event to delete.

​
POST /web-app/bulk-import-academic-calendar-json

Request Body: 
{
  "skole_id": "SKL001",
  "records": [
    {
      "title": "Winter Break",
      "event_type": "holiday",
      "event_from_date": "2024-12-24",
      "event_to_date": "2025-01-02"
    }
  ]
}

​
5. Response Structure

​
Success: Parent Event View (200 OK)

Route: GET /parent-app/academic-events 
{
  "success": true,
  "data": [
    {
      "id": 45,
      "title": "Sports Day",
      "event_type": "event",
      "event_from_date": "2024-12-20"
    }
  ]
}

​
Success: Staff Calendar List (200 OK)

Route: GET /teachers-app/academic-calendar 
{
  "success": true,
  "data": [
    {
      "id": 45,
      "title": "Sports Day",
      "event_type": "event",
      "skole_id": "SKL001"
    }
  ]
}

​
Success: Event Created (201 Created)

Route: POST /{module}/academic-calendar 
{
  "success": true,
  "message": "Academic event added",
  "data": { "id": 46 }
}

​
Success: Event Updated (200 OK)

Route: PUT /teachers-app/academic-calendar/:id 
{
  "success": true,
  "message": "Event details updated"
}

​
Success: Event Deleted (200 OK)

Route: DELETE /teachers-app/academic-calendar/:id 
{
  "success": true,
  "message": "Event removed"
}

​
Success: Admin Event Dashboard (200 OK)

Route: GET /web-app/academic-calendar 
{
  "success": true,
  "data": {
    "events": [...],
    "total_count": 25
  }
}

​
Success: Bulk Import JSON (200 OK)

Route: POST /web-app/bulk-import-academic-calendar-json 
{
  "success": true,
  "message": "Bulk import successful",
  "data": { "count": 10 }
}

​
6. Error Responses

HTTP CodeDescription
404Event not found
400Date format error or missing required fields

​
7. Security Considerations

  • Scoping: Enforced via skole_id.
  • RBAC: Only staff with calendar.manage permission can create or edit events.

​
8. Token Usage

GET /parent-app/academic-events
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/academic-events?event_type=holiday"

​
12. Notes / Special Behaviors

  • Multi-day Events: If event_to_date is different from event_from_date, the mobile app displays the event as a span across the calendar.
  • Color Coding: Similar to the Noticeboard, event types trigger specific UI highlights (e.g., Red for exam, Green for holiday).