lw-lms-rest-frontend

Builds learner frontends against LW LMS 2.0.0 `/wp-json/lms/v1`, including catalog status filters, access gates, linear/drip locks, quizzes, ready video HTML, progress, and signed protected downloads.

SKILL.md

GitHub

LW LMS REST frontend

Consume the headless learner API. The plugin ships no public templates, shortcodes, or blocks.

Routes

Namespace: lms/v1.

Method Path Gate
GET /courses public; non-published status filters need matching edit capability
GET /courses/{id} public for published; capable users can preview non-published
GET /lessons/{id} access, visibility, and drip lock
GET /progress current logged-in user
GET /progress/course/{id} current logged-in user
POST /progress login, course/lesson match, access, drip, optional quiz gate
POST /lessons/{id}/quiz login, access, drip, attempt limits
GET /download/{id} signed link, ownership, current access, visibility

The React admin uses the separate lw-lms/v1/admin/* namespace. Do not call those routes from a learner frontend.

Authentication

  • Public catalog: no authentication.
  • Logged-in browser: WordPress cookie, credentials: 'same-origin', and X-WP-Nonce.
  • Headless/mobile: Application Passwords or another reviewed authentication layer.
  • Downloads: use the signed URL from the payload in the same user context.
await fetch('/wp-json/lms/v1/progress', {
  method: 'POST',
  credentials: 'same-origin',
  headers: {
    'Content-Type': 'application/json',
    'X-WP-Nonce': wpApiSettings.nonce,
  },
  body: JSON.stringify({ course_id: 42, lesson_id: 100, status: 'completed' }),
});

Access and visibility

Course content is public marketing copy. It is not evidence of enrollment. Gate the player with access.has_access and each lesson row's accessible value.

Course list access checks do not lazily enroll a viewer in a free course. Opening the full free course can create the enrollment row.

GET /courses accepts status=publish|private|draft|any. A non-published request without the necessary type capability fails with rest_forbidden_status; authorized results are then filtered again by per-post capability. Treat the server's result as authoritative; do not emulate WordPress status capability logic in JavaScript.

Render both sections[].lessons and lessons_without_section. Keep inaccessible lessons visible as syllabus rows with lock state.

Drip state

Course detail includes progression. Lesson rows include:

  • accessible;
  • locked_reason: sequence, schedule, or null;
  • available_at: ISO 8601 or null;
  • completed.

Locked lesson detail, progress, quiz, and download requests return 403 lesson_locked with the same reason and time. Render server data; do not calculate schedules in the client.

Lesson, video, and quiz

Lesson detail includes rendered content, editor-only content_raw, course/section, navigation, attachments, quiz, and video.

Since 1.9.1, video.html is ready-to-render player markup. When LW Cookie 1.7.1+ blocks the provider before consent, it can be a consent placeholder. Sanitize only according to your trusted-server rendering policy; do not rebuild embeds from the URL and bypass consent handling.

quiz contains no correct answers. Submit learner answers to /lessons/{id}/quiz; then refresh progress when a required passing quiz can complete the lesson. Use lw-lms-quiz-integration for the exact schema and limits.

Signed downloads

download_url now includes a user-bound signature and expiry. Default lifetime is one hour. Do not cache it across users, persist it as the attachment URL, strip its query parameters, or reconstruct it from the attachment ID. The server rechecks current access and attachment ownership at use time.

The response is binary. Use a normal link or a blob response, never response.json().

Payload extensions

Companion plugins can add top-level fields through:

  • lw_lms_rest_course_list_item;
  • lw_lms_rest_course;
  • lw_lms_rest_lesson.

Core fields cannot be replaced or removed. Make client parsers tolerate additional top-level keys while continuing to require documented core keys.

Critical rules

  • Use access.has_access; course content is public.
  • Render locked_reason separately from entitlement denial.
  • Treat available_at as the server's timestamp.
  • Do not assume public route registration means public content.
  • Treat content_raw as editor data.
  • Use course_progress.completed_lessons, not completed_count.
  • Use option IDs for quiz answers; displayed order may be shuffled.
  • Refresh signed download URLs instead of storing them.
  • Snapshot the JSON shapes in frontend tests because the plugin is still under active development.

Detailed contract

Read references/rest-response-contract.md for collection parameters, response fields, progress errors, quiz response, and download behavior.

Cross-references

  • Use lw-lms-drip-progression for schedule configuration and diagnosis.
  • Use lw-lms-quiz-integration for quiz authoring and attempt behavior.
  • Use lw-lms-backend-extend for PHP hooks and payload filters.
  • Use lw-lms-abilities for admin/agent operations; abilities are not learner REST.

References

  • Official repository: https://github.com/lwplugins/lw-lms
  • Verified source paths:
    • includes/Api/RestApi.php
    • includes/Api/Controllers/
    • includes/Api/Transformers/
    • includes/Api/LessonRestGuard.php
    • includes/Api/DownloadLink.php
    • includes/Video/EmbedRenderer.php