LMS API overview
API overview (LMS)
Section titled “API overview (LMS)”Audience: backend, frontend, qa
Status: specced
Owns: backend
Depends on: LMS overview, Lifecycle, Data model, Architecture handover
Contract rule
Section titled “Contract rule”OpenAPI is the HTTP source of truth for LMS client APIs. Design SoT is ecosystem-root lms-openapi.yaml; this docs site publishes openapi/lms.yaml. Frontend must not reverse-engineer screens for endpoints.
Envelope matches Orchestrator / CAP (§19): list endpoints return { success, data: [ ... ], meta? } — data is the array itself, not { items: [...] }. Pagination (when present) is only in meta.pagination.
Artifact location
Section titled “Artifact location”| Item | Convention |
|---|---|
| Design SoT | lms-openapi.yaml (ecosystem root) |
| Prisma | Implemented in elimi-ecosystem/apps/lms/prisma/; design seed lms-schema.prisma |
| Published copy | openapi/lms.yaml in elimi-documentation |
| Interactive | Scalar — LMS REST |
| Orchestrator auth / address / storage | openapi/orchestrator.yaml |
| gRPC recs | lms.v1.RecommendationsService in @yourorg/proto |
| Gateway prefix | /v1/lms |
| Local | http://localhost:4200/v1 |
Not on this REST surface
Section titled “Not on this REST surface”- Login / JWT / Address lists / Storage upload / Notifications → Orchestrator
- Payment processing → OL
InitiatePayment(self-pay). Cohort invoices are OL REST. LMS checkout may returnsettlement: organization_cohort. - CAP recommendations → gRPC, not public OpenAPI
Resource groups
Section titled “Resource groups”| Group | Use | Notes |
|---|---|---|
| Me | GET /me, GET/PATCH /me/profile |
Personas, onboarding gates, capabilities; person name + photo + learner onboarding person blocks |
| Onboarding | start / mine / get / save / submit per persona | Multi-persona allowed |
| Catalogue | published courses + outline | Public browse (security: []). Optional Bearer. Resolved thumbnail on list/detail/outline. |
| Authoring | courses, modules, items, sequencing, publish | SCORM via OL packageAssetId |
| Level offerings | catalogue, staff compose/publish, fan-out enroll + checkout | Public published GETs; enroll/checkout authenticated. Thumbnail from first member course with one. |
| Instructors | invites, co-instructors | Platform invite only |
| Enrollments | enroll, checkout, admin grants | Entitlement sources include organization_seat |
| Player | progress, launch, SCORM CMI + player HTML | lms.sequencing.locked. See SCORM player. |
| Assessments | native quiz attempts | SCORM quizzes stay inside the package |
| Certificates | LMS-owned | Independent of CAP |
| Staff | invites, roles, directory person fields, enrollment lookup, platform settings | Staff ⊇ instructor. GET /staff returns name, email, photo. GET/PATCH /admin/settings is the Settings screen. |
| Learners | directory, export, invite, LMS-local suspend, admin enroll, OL org proxy | learner.manage; planned org-scoped list/detail (ORG-44) |
| Seat allocations | LMS projection of sponsored seats | CSV or rows; canonical paid cohort is OL (ORG-43/45) |
| Admin payments | checkout ledger + receipt snapshot | payments.read (staff admin). Course self-pay + level enrollments; no fan-out double count; grants omitted. Receipt is JSON only. |
| Admin dashboard | year-filtered KPIs and charts | analytics.read (staff admin). Query year is a UTC calendar year (default current). Cohort dates: learners LearnerProfile.createdAt, courses publishedAt, certified LmsCertificate.issuedAt, active enrollments Enrollment.createdAt + ACTIVE, revenue checkout.completedAt, rankings createdAt. Gender uses the same learner set as totalLearners. Top courses/levels rank by enrollment volume (default top 5). |
| Admin settings | Contact + terms / privacy / refund | settings.read / settings.write (staff admin). Each legal section is typed text or a PDF documentAssetId (upload via OL storage first). |
SCORM player
Section titled “SCORM player”Do not open launchUrl in a browser or iframe. That URL is JSON session metadata (GET /player/scorm/{sessionId}).
| Field / route | Client use |
|---|---|
POST /enrollments/{id}/items/{id}/launch |
Start. Returns sessionId, launchUrl (JSON), playerUrl, contentBaseUrl |
playerUrl |
Iframe this from the client origin. LMS HTML shell (GET …/player?ct=). Sets window.API (SCORM 1.2) and iframes scoHref?ct= |
GET /player/scorm/{sessionId} |
Resume metadata + last cmi. Same Bearer as launch |
GET /player/scorm/{sessionId}/content/{path} |
Extracted package files (used by the shell). Path-jailed |
POST /player/scorm/{sessionId}/cmi |
Owned by the shell. Do not POST …/items/{id}/progress for SCORM |
Player HTML, package files, and CMI accept Bearer or a short-lived content token (ct query, lms_scorm_ct cookie, X-Elimi-Scorm-Token, or Referer ct). ct is bound to the enrollment learner. HTTPS sets SameSite=None; Secure; Partitioned. Set LMS_PUBLIC_BASE_URL to the OpenAPI server the client calls (…/v1/lms on the gateway) and LMS_SCORM_CONTENT_TOKEN_SECRET in production.
Interactive spec: Scalar — LMS REST (getScormPlayer, getScormContent).
Suggested implementation order
Section titled “Suggested implementation order”lms_users+user.created+GET /me+ onboarding- Staff/instructor invites
- Authoring + publish + catalogue
- Entitlements + checkout (
payment.completed) - Player + sequencing + native assessments + SCORM runtime
- Completion policy + LMS certificate +
lms.course.completed - gRPC
RecommendCourses(replace CAP mock) - Admin learners + OL organization proxy + seat allocations (
organization_seat) - Admin payments ledger + year-filtered dashboard (
GET /admin/payments*,GET /admin/dashboard)