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.mdlw-plugins/lw-lms-rest-frontend/SKILL.md
GitHubLW 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', andX-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; coursecontentis public. - Render
locked_reasonseparately from entitlement denial. - Treat
available_atas the server's timestamp. - Do not assume public route registration means public content.
- Treat
content_rawas editor data. - Use
course_progress.completed_lessons, notcompleted_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-progressionfor schedule configuration and diagnosis. - Use
lw-lms-quiz-integrationfor quiz authoring and attempt behavior. - Use
lw-lms-backend-extendfor PHP hooks and payload filters. - Use
lw-lms-abilitiesfor admin/agent operations; abilities are not learner REST.
References
- Official repository: https://github.com/lwplugins/lw-lms
- Verified source paths:
includes/Api/RestApi.phpincludes/Api/Controllers/includes/Api/Transformers/includes/Api/LessonRestGuard.phpincludes/Api/DownloadLink.phpincludes/Video/EmbedRenderer.php