Academic Calendar

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

Method	Route	Auth	Description
GET	`/parent-app/academic-events`	🔐 JWT	View upcoming academic events
GET	`/teachers-app/academic-calendar`	🔐 JWT	Staff: View all scheduled events
POST	`/teachers-app/academic-calendar`	🔐 JWT	Staff: Create a new academic event
PUT	`/teachers-app/academic-calendar/:id`	🔐 JWT	Staff: Update event details
DELETE	`/teachers-app/academic-calendar/:id`	🔐 JWT	Staff: Soft-delete an event
GET	`/web-app/academic-calendar`	🔐 JWT	Admin: Comprehensive event list
POST	`/web-app/academic-calendar`	🔐 JWT	Admin: Create academic event
POST	`/web-app/bulk-import-academic-calendar-json`	🔐 JWT	Admin: 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:

Field	Type	Required	Description
skole_id	string	Yes	School identifier.
event_type	string	No	Filter by type (holiday/event).
from_date	string	No	Start date filter (YYYY-MM-DD).
to_date	string	No	End 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:

Field	Type	Description
id	number	ID 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 Code	Description
404	Event not found
400	Date 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).

Modules

API

Data Schema

Changelog

1. API Purpose

2. Endpoint Definition

3. Authentication Flow

4. Request Structure

GET /parent-app/academic-events

GET /web-app/academic-calendar

POST /web-app/academic-calendar

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

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

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

5. Response Structure

Success: Parent Event View (200 OK)

Success: Staff Calendar List (200 OK)

Success: Event Created (201 Created)

Success: Event Updated (200 OK)

Success: Event Deleted (200 OK)

Success: Admin Event Dashboard (200 OK)

Success: Bulk Import JSON (200 OK)

6. Error Responses

7. Security Considerations

8. Token Usage

9. Token Refresh

10. Logout / Session Invalidation

11. Usage Example (cURL)

12. Notes / Special Behaviors

​1. API Purpose

​2. Endpoint Definition

​3. Authentication Flow

​4. Request Structure

​GET /parent-app/academic-events

​GET /web-app/academic-calendar

​POST /web-app/academic-calendar

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

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

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

​5. Response Structure

​Success: Parent Event View (200 OK)

​Success: Staff Calendar List (200 OK)

​Success: Event Created (201 Created)

​Success: Event Updated (200 OK)

​Success: Event Deleted (200 OK)

​Success: Admin Event Dashboard (200 OK)

​Success: Bulk Import JSON (200 OK)

​6. Error Responses

​7. Security Considerations

​8. Token Usage

​9. Token Refresh

​10. Logout / Session Invalidation

​11. Usage Example (cURL)

​12. Notes / Special Behaviors

1. API Purpose

2. Endpoint Definition

3. Authentication Flow

4. Request Structure

GET /parent-app/academic-events

GET /web-app/academic-calendar

POST /web-app/academic-calendar

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

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

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

5. Response Structure

Success: Parent Event View (200 OK)

Success: Staff Calendar List (200 OK)

Success: Event Created (201 Created)

Success: Event Updated (200 OK)

Success: Event Deleted (200 OK)

Success: Admin Event Dashboard (200 OK)

Success: Bulk Import JSON (200 OK)

6. Error Responses

7. Security Considerations

8. Token Usage

9. Token Refresh

10. Logout / Session Invalidation

11. Usage Example (cURL)

12. Notes / Special Behaviors