openedx-owly-apis 1.6.0

One-line description for README and other doc files.

openedx-owly-apis

Extra API endpoints for Open edX

This Django app provides additional REST API endpoints for Open edX to enable advanced features such as analytics, course management, and role inspection. It is intended to be deployed inside an Open edX platform using Tutor.

Installation (via Tutor plugin)

Use the Tutor plugin from aulasneo to install and enable these APIs inside your Open edX deployment:

• Repository: https://github.com/aulasneo/tutor-contrib-owly

Quick start with Tutor:

1. Install the plugin

   tutor plugins install git+https://github.com/aulasneo/tutor-contrib-owly.git

2. Enable and configure

   tutor plugins enable owly
   tutor config save

3. Apply and start

   tutor images build openedx
   tutor local launch

Once enabled, the app is included in LMS and exposes endpoints under the paths registered by openedx_owly_apis/urls.py.

API Summary

Base router registrations are defined in openedx_owly_apis/urls.py:

• /owly-analytics/ → OpenedXAnalyticsViewSet

• /owly-config/ → OpenedXConfigViewSet

• /owly-courses/ → OpenedXCourseViewSet

• /owly-roles/ → OpenedXRolesViewSet

Authentication is supported via JWT/Bearer/Session. Specific permissions are enforced per endpoint (see notes below).

Configuration endpoints (GET)

ViewSet: openedx_owly_apis/views/config_openedx.py Requires: Authenticated user.

• GET /owly-config/enable_owly_chat Check if the Owly chat feature is enabled via waffle flag. Can check for a specific user by providing an email query parameter.

Analytics endpoints (GET)

ViewSet: openedx_owly_apis/views/analytics.py Requires: Admin or Course Staff permissions.

• GET /owly-analytics/overview?course_id=<course-key> Returns overview analytics for a course or platform-wide stats.

• GET /owly-analytics/enrollments?course_id=<course-key> Returns detailed enrollment analytics for a course.

• GET /owly-analytics/discussions?course_id=<course-key> Returns forum analytics and configuration for a course.

• GET /owly-analytics/detailed?course_id=<course-key> Returns a comprehensive, combined analytics payload for a course.

Course management endpoints (POST)

ViewSet: openedx_owly_apis/views/courses.py Requires: Authenticated user. Additional role-based permissions per action.

• POST /owly-courses/create Create a new course. Requires admin or course creator.

• POST /owly-courses/structure Create or edit course structure. Requires admin, course creator, or course staff.

• POST /owly-courses/content/html Add HTML content to a vertical. Requires admin, course creator, or course staff.

• POST /owly-courses/content/video Add video content to a vertical. Requires admin, course creator, or course staff.

• POST /owly-courses/content/problem Add problems/exercises to a vertical using XML. Requires admin, course creator, or course staff.

• POST /owly-courses/content/problem/create Create a problem component with structured data (e.g., multiple choice). Requires admin, course creator, or course staff.

• POST /owly-courses/content/discussion Add discussion components to a vertical. Requires admin, course creator, or course staff.

• POST /owly-courses/content/publish Publish a course or course component (unit, subsection, etc.). Requires admin or course staff.

• POST /owly-courses/xblock/delete Delete an XBlock component from a course. Requires admin or course staff.

• POST /owly-courses/settings/update Update general course settings (dates, details, etc.). Requires admin or course staff.

• POST /owly-courses/settings/advanced Update advanced course settings. Requires admin or course staff.

• POST /owly-courses/certificates/configure Configure or activate/deactivate course certificates. Requires admin or course staff.

• POST /owly-courses/units/availability/control Control unit availability and due dates. Requires admin or course staff.

Staff management endpoints

• POST /owly-courses/staff/manage Add or remove a user from a course staff role (staff or course_creator). Requires admin or course staff.

• GET /owly-courses/staff/list?course_id=<course-key> List users with staff roles for a given course. Requires admin or course staff.

Roles endpoint (GET)

ViewSet: openedx_owly_apis/views/roles.py Requires: Authenticated user.

• GET /owly-roles/me?course_id=<course-key>&org=<org-key> Returns the effective role of the authenticated user, including flags for:

  • superadmin (Django superuser or global staff)

  • course_staff (instructor/staff/limited_staff for given course)

  • course_creator (global or org-specific according to platform settings)

  • authenticated

Permissions and Authentication

• Authentication classes: JWT (JwtAuthentication), Bearer (BearerAuthentication), Session.

• Permissions:

  • Analytics: IsAdminOrCourseStaff

  • Courses: action-specific guards such as IsAdminOrCourseCreator, IsAdminOrCourseCreatorOrCourseStaff, IsAdminOrCourseStaff

  • Roles: IsAuthenticated

Development

• Source paths of interest:

  • Views: openedx_owly_apis/views/

  • Operations logic: openedx_owly_apis/operations/

  • URL routing: openedx_owly_apis/urls.py

License

AGPL-3.0. See LICENSE.txt.

Project Links

• CI: https://github.com/aulasneo/openedx-owly-apis/actions/workflows/ci.yml

• Issues: https://github.com/aulasneo/openedx-owly-apis/issues

Change Log

Version 1.6.0 (2025-12-11)

Added

• Grade Management: - Add grade management operations for student assessments

Changed

• Simplify API URL structure by removing redundant path prefixes

• Standardize whitespace and improve logging in grade management operations

• Extract parse_grade_id function to validators module with comprehensive test coverage

Version 1.5.0 (2025-10-31)

Added

• Course Tree API: - Add endpoint with search and traversal capabilities - Implement CMS-first course tree building with modulestore traversal and debug logging - Support draft and published modulestore branches

• Unit Contents: - Add API endpoint to fetch unit contents and their raw data

• ORA Grading: - Add student response extraction and improve workflow handling

Changed

• Refactor permission to IsAdminOrCourseStaff

Fixed

• Update permission requirements for unit contents endpoint

Version 1.4.0 (2025-10-22)

Added

• Course Staff Management APIs: - POST /staff/manage: Add or remove users from course staff roles (staff, course_creator) - GET /staff/list: List all users with course staff roles, with optional role filtering - Support for simplified role types: staff and course_creator roles - Enhanced role management with detailed user information

• Open Response Assessment (ORA) Management: - POST /content/ora: Create ORA components with full configuration support - POST /content/ora/grade: Grade ORA submissions using staff assessment - GET /content/ora/details: Get detailed ORA information including rubric structure - GET /content/ora/submissions: List all submissions for an ORA component - Support for peer assessment, self-assessment, and staff assessment workflows - Comprehensive rubric management and grading capabilities

• Cohort Management APIs: - POST /cohorts/create: Create new cohorts with manual or random assignment - GET /cohorts/list: List all cohorts in a course - POST /cohorts/members/add: Add users to specific cohorts - POST /cohorts/members/remove: Remove users from cohorts - GET /cohorts/members/list: List all members of a cohort - DELETE /cohorts/delete: Delete cohorts and their memberships

Changed

• Reorganized course management endpoints with clearer permission models

• Enhanced error handling and validation across all endpoints

• Improved documentation with detailed examples and error scenarios

• Standardized response formats across all API endpoints

• Improved submission retrieval logic and error handling in ORA functions

• Refactored ORA content logic and tests for clarity

Documentation

• Added comprehensive API documentation for course staff management

• Detailed ORA workflow documentation with grading examples

• Cohort management usage examples and best practices

• Enhanced endpoint documentation with request/response examples

• Fixed changelog header underline length

• Formatting cleanups and clarity improvements in ORA documentation

Version 1.2.0 (2025-09-23)

Added

• Add course staff management endpoints and enhance waffle flag checks (ed44fa2)

• Add OpenedXConfigViewSet for managing Owly chat feature toggle (5b480a2)

Changed

• Remove unused authentication and permission imports from config view (d2e6e98)

• Remove authentication and permission classes from OpenedXConfigViewSet (1146370)

Documentation

• Improve API documentation formatting and clarity for course staff endpoints (db63cbe)

Version 1.1.0 (2025-09-08)

Added

• Problem creation endpoints and logic for multiple problem types: - Support for dropdown problems with XML generation - Enhanced XML generation for multiple choice problems with input validation and escaping - POST /add_problem_content endpoint for problem integration

• Content publishing functionality: - POST /publish endpoint for publishing courses and units - Content publishing logic with modulestore integration

• XBlock management capabilities: - POST /delete_xblock endpoint for removing course components - Delete XBlock logic with modulestore integration

• Certificate management enhancements: - Toggle certificate logic for managing certificate active status - Certificate activation/deactivation integration in course configuration - Simplified certificate activation logic without certificate_id requirement

Changed

• Enhanced XML generation for problem types with improved input validation and error handling

• Reorganized imports in courses.py for better code readability

• Updated delete_xblock logic to use acting_user parameter consistently

Fixed

• Corrected delete_xblock logic parameter usage from user_identifier to acting_user

Version 1.0.0 (2025-08-27)

Added

• DRF ViewSets and endpoints for analytics: overview, enrollments, discussions, detailed under /owly-analytics/ (see openedx_owly_apis/views/analytics.py).

• Course management endpoints under /owly-courses/ (see openedx_owly_apis/views/courses.py): - POST /create: create course. - POST /structure: create/edit course structure (chapters, subsections, verticals). - POST /content/html: add HTML component to vertical. - POST /content/video: add Video component to vertical. - POST /content/problem: add Problem component to vertical. - POST /content/discussion: add Discussion component to vertical. - POST /settings/update: update course settings (dates/details/etc.). - POST /settings/advanced: update advanced settings. - POST /certificates/configure: enable/configure certificates. - POST /units/availability/control: control unit availability and due dates.

• Roles endpoint under /owly-roles/me to determine effective user role (see openedx_owly_apis/views/roles.py).

• Authentication via JwtAuthentication and SessionAuthentication across ViewSets.

Documentation

• README: comprehensive API overview, endpoint list, and Tutor plugin installation instructions for tutor-contrib-owly.