Academic Sessions - API Reference

Audience: Frontend engineers, mobile engineers, backend engineers, QA, and API consumers. Scope: Admin-facing API owned by AcademicSessionsModule. No public or mobile-facing route exists.

1. Documentation Evidence

2. Module Summary

3. Concepts and Terminology

4. API Surface Map

There is no separate "make current" route. Making a session current is PATCH /api/academic-sessions/:publicId with { "isCurrent": true } in the body — verified against academic-sessions.controller.ts, which declares only the four routes above.

5. The "Exactly One Current Session" Rule

This rule is split between the database and the service, and the two halves are enforced differently on purpose.

Both create and update unset the incumbent session inside the same database transaction as the write that sets the new one, and always in that order — unset first, then set. Setting a second isCurrent = true row before clearing the first would violate the partial unique index at the INSERT/UPDATE itself, regardless of which write the caller intended to win.

6. DTO and Model Reference

6.1 AcademicSessionDto (response)

6.2 CreateAcademicSessionDto (body)

endDate must be strictly after startDate — enforced both by the service (AcademicSessionsService.assertDatesOrdered, a readable pre-check) and by the database CHECK constraint academic_sessions_dates_ordered (the actual guarantee). A duplicate name is rejected case-insensitively.

6.3 UpdateAcademicSessionDto (body, PATCH)

6.4 ListAcademicSessionsQueryDto (query)

Extends the shared QueryDto (search, page, size, sort, order, pagination — inherited, never redeclared) and adds:

sort accepts "name" or "endDate"; anything else (including the default) sorts by startDate — academic-sessions.service.ts, findAll. Every list is tie-broken by id ascending after the requested sort column.

7. Endpoint Reference

7.1 GET /api/academic-sessions

Purpose: Paginated, filterable list of sessions.

Auth: JwtAuthGuard, RoleGuard; permission AcademicSessions_READ.

Query: search, isActive, isCurrent, pagination, page, size, sort (name | endDate | default startDate), order.

Response:

{
  "message": "Academic sessions fetched.",
  "data": [
    {
      "id": 3,
      "publicId": "018f2a1e-6b1e-7c3a-9d2e-1a2b3c4d5e6f",
      "name": "2026-27",
      "startDate": "2026-04-15",
      "endDate": "2027-04-14",
      "isCurrent": true,
      "isActive": true,
      "createdAt": "2026-04-01T00:00:00.000Z",
      "updatedAt": "2026-04-01T00:00:00.000Z"
    }
  ],
  "errorCode": null,
  "count": 1,
  "currentPage": 1,
  "totalPage": 1
}

Side effects: A Redis cache read (getSoft) is tried first on a key folding the full query (search, isActive, isCurrent, sort, order, pagination, page, size); on a miss, a SELECT (plus a COUNT(*) when paginated) followed by a setSoft at a 3600-second TTL.

Errors: 401 AUTH_UNAUTHENTICATED, 403 PERMISSION_INSUFFICIENT, 400 VALIDATION_FAILED.

7.2 POST /api/academic-sessions

Purpose: Create a session, optionally making it current immediately.

Auth: permission AcademicSessions_CREATE.

Body: CreateAcademicSessionDto (see 6.2).

Side effects: If isCurrent: true, the existing current session (if any) is unset inside the same transaction before the insert. Always invalidates the list cache (delPatternSoft over academic-sessions:*) after commit.

Errors:

7.3 PATCH /api/academic-sessions/:publicId

Purpose: Update any subset of a session's fields. This is also the only way to make a session current — there is no separate "set current" route.

Auth: permission AcademicSessions_UPDATE.

Body: UpdateAcademicSessionDto (see 6.3).

Behavior:

• { "isCurrent": true } unsets the existing current session (excluding this row) and sets this one, in one transaction.
• { "isCurrent": false } on the session that is currently the only current one is refused with 409 ACADEMIC_SESSION_CURRENT_REQUIRED — a school always has exactly one current session, and this half of the rule cannot be expressed as a database constraint (see Section 5).
• A PATCH that supplies only one of startDate/endDate is checked against the stored value of the other field, not just the supplied one — otherwise a caller could invert the range across two separate requests and have the database CHECK constraint report an unmapped 23514.

Errors:

7.4 DELETE /api/academic-sessions/:publicId

Purpose: Hard delete. There is no deleted_at on academic_sessions — retire a session with PATCH { "isActive": false } instead, which removes it from pick lists while leaving any existing reference to it intact.

Auth: permission AcademicSessions_DELETE.

Behavior: Refused when the session is the current one.

Errors:

As of this doc, no other schema references academic_sessions.id, so no foreign-key conflict (23503) can occur on delete yet — the service's own docblock (academic-sessions.service.ts, remove) notes this is expected to change once classes/enrolment land, at which point a 23503 guard is added.

8. Error Code Reference

Source: apps/api/src/common/types/error-codes.ts, lines 258-281.

See Also

• Backend doc: /docs/developer/academic-sessions/backend
• Feature and flows doc: /docs/developer/academic-sessions/feature