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
.. code-block:: bash
tutor plugins install git+https://github.com/aulasneo/tutor-contrib-owly.git
2. Enable and configure
.. code-block:: bash
tutor plugins enable owly
tutor config save
3. Apply and start
.. code-block:: bash
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-courses/`` → ``OpenedXCourseViewSet``
- ``/owly-roles/`` → ``OpenedXRolesViewSet``
Authentication is supported via JWT/Bearer/Session. Specific permissions are enforced per endpoint (see notes below).
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. 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/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 course certificates. Requires admin or course staff.
- ``POST /owly-courses/units/availability/control``
Control unit availability and due dates. 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 <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
##########
..
All enhancements and patches to openedx_owly_apis will be documented
in this file. It adheres to the structure of https://keepachangelog.com/ ,
but in reStructuredText instead of Markdown (for ease of incorporation into
Sphinx documentation and the PyPI description).
This project adheres to Semantic Versioning (https://semver.org/).
.. There should always be an "Unreleased" section for changes pending release.
Unreleased
**********
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``.
Raw data
{
"_id": null,
"home_page": "https://github.com/aulasneo/openedx-owly-apis",
"name": "openedx-owly-apis",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "Python edx",
"author": "lberoes@aulasneo.com",
"author_email": "lberoes@aulasneo.com",
"download_url": "https://files.pythonhosted.org/packages/17/af/04fc920108aff39fe69dfae99b631b65ee6d6e3d559eb282b2a5ef47b444/openedx_owly_apis-1.0.0.tar.gz",
"platform": null,
"description": "openedx-owly-apis\n#################\n\nExtra API endpoints for Open edX\n********************************\n\nThis 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.\n\nInstallation (via Tutor plugin)\n*******************************\n\nUse the Tutor plugin from aulasneo to install and enable these APIs inside your Open edX deployment:\n\n- Repository: https://github.com/aulasneo/tutor-contrib-owly\n\nQuick start with Tutor:\n\n1. Install the plugin\n\n .. code-block:: bash\n\n tutor plugins install git+https://github.com/aulasneo/tutor-contrib-owly.git\n\n2. Enable and configure\n\n .. code-block:: bash\n\n tutor plugins enable owly\n tutor config save\n\n3. Apply and start\n\n .. code-block:: bash\n\n tutor images build openedx\n tutor local launch\n\nOnce enabled, the app is included in LMS and exposes endpoints under the paths registered by ``openedx_owly_apis/urls.py``.\n\nAPI Summary\n***********\n\nBase router registrations are defined in ``openedx_owly_apis/urls.py``:\n\n- ``/owly-analytics/`` \u2192 ``OpenedXAnalyticsViewSet``\n- ``/owly-courses/`` \u2192 ``OpenedXCourseViewSet``\n- ``/owly-roles/`` \u2192 ``OpenedXRolesViewSet``\n\nAuthentication is supported via JWT/Bearer/Session. Specific permissions are enforced per endpoint (see notes below).\n\nAnalytics endpoints (GET)\n=========================\n\nViewSet: ``openedx_owly_apis/views/analytics.py``\nRequires: Admin or Course Staff permissions.\n\n- ``GET /owly-analytics/overview?course_id=<course-key>``\n Returns overview analytics for a course or platform-wide stats.\n\n- ``GET /owly-analytics/enrollments?course_id=<course-key>``\n Returns detailed enrollment analytics for a course.\n\n- ``GET /owly-analytics/discussions?course_id=<course-key>``\n Returns forum analytics and configuration for a course.\n\n- ``GET /owly-analytics/detailed?course_id=<course-key>``\n Returns a comprehensive, combined analytics payload for a course.\n\nCourse management endpoints (POST)\n==================================\n\nViewSet: ``openedx_owly_apis/views/courses.py``\nRequires: Authenticated user. Additional role-based permissions per action.\n\n- ``POST /owly-courses/create``\n Create a new course. Requires admin or course creator.\n\n- ``POST /owly-courses/structure``\n Create or edit course structure. Requires admin, course creator, or course staff.\n\n- ``POST /owly-courses/content/html``\n Add HTML content to a vertical. Requires admin, course creator, or course staff.\n\n- ``POST /owly-courses/content/video``\n Add video content to a vertical. Requires admin, course creator, or course staff.\n\n- ``POST /owly-courses/content/problem``\n Add problems/exercises to a vertical. Requires admin, course creator, or course staff.\n\n- ``POST /owly-courses/content/discussion``\n Add discussion components to a vertical. Requires admin, course creator, or course staff.\n\n- ``POST /owly-courses/settings/update``\n Update general course settings (dates, details, etc.). Requires admin or course staff.\n\n- ``POST /owly-courses/settings/advanced``\n Update advanced course settings. Requires admin or course staff.\n\n- ``POST /owly-courses/certificates/configure``\n Configure course certificates. Requires admin or course staff.\n\n- ``POST /owly-courses/units/availability/control``\n Control unit availability and due dates. Requires admin or course staff.\n\nRoles endpoint (GET)\n====================\n\nViewSet: ``openedx_owly_apis/views/roles.py``\nRequires: Authenticated user.\n\n- ``GET /owly-roles/me?course_id=<course-key>&org=<org-key>``\n Returns the effective role of the authenticated user, including flags for:\n\n - ``superadmin`` (Django superuser or global staff)\n - ``course_staff`` (instructor/staff/limited_staff for given course)\n - ``course_creator`` (global or org-specific according to platform settings)\n - ``authenticated``\n\nPermissions and Authentication\n********************************\n- Authentication classes: JWT (``JwtAuthentication``), Bearer (``BearerAuthentication``), Session.\n- Permissions:\n\n - Analytics: ``IsAdminOrCourseStaff``\n - Courses: action-specific guards such as ``IsAdminOrCourseCreator``, ``IsAdminOrCourseCreatorOrCourseStaff``, ``IsAdminOrCourseStaff``\n - Roles: ``IsAuthenticated``\n\nDevelopment\n***********\n\n- Source paths of interest:\n\n - Views: ``openedx_owly_apis/views/``\n - Operations logic: ``openedx_owly_apis/operations/``\n - URL routing: ``openedx_owly_apis/urls.py``\n\nLicense\n*******\n\nAGPL-3.0. See `LICENSE.txt <LICENSE.txt>`_.\n\nProject Links\n*************\n\n- CI: https://github.com/aulasneo/openedx-owly-apis/actions/workflows/ci.yml\n- Issues: https://github.com/aulasneo/openedx-owly-apis/issues\n\n\n\nChange Log\n##########\n\n..\n All enhancements and patches to openedx_owly_apis will be documented\n in this file. It adheres to the structure of https://keepachangelog.com/ ,\n but in reStructuredText instead of Markdown (for ease of incorporation into\n Sphinx documentation and the PyPI description).\n\n This project adheres to Semantic Versioning (https://semver.org/).\n\n.. There should always be an \"Unreleased\" section for changes pending release.\n\nUnreleased\n**********\n\nAdded\n=====\n\n* DRF ViewSets and endpoints for analytics: ``overview``, ``enrollments``, ``discussions``, ``detailed`` under ``/owly-analytics/`` (see ``openedx_owly_apis/views/analytics.py``).\n* Course management endpoints under ``/owly-courses/`` (see ``openedx_owly_apis/views/courses.py``):\n - ``POST /create``: create course.\n - ``POST /structure``: create/edit course structure (chapters, subsections, verticals).\n - ``POST /content/html``: add HTML component to vertical.\n - ``POST /content/video``: add Video component to vertical.\n - ``POST /content/problem``: add Problem component to vertical.\n - ``POST /content/discussion``: add Discussion component to vertical.\n - ``POST /settings/update``: update course settings (dates/details/etc.).\n - ``POST /settings/advanced``: update advanced settings.\n - ``POST /certificates/configure``: enable/configure certificates.\n - ``POST /units/availability/control``: control unit availability and due dates.\n* Roles endpoint under ``/owly-roles/me`` to determine effective user role (see ``openedx_owly_apis/views/roles.py``).\n* Authentication via ``JwtAuthentication`` and ``SessionAuthentication`` across ViewSets.\n\nDocumentation\n=============\n\n* README: comprehensive API overview, endpoint list, and Tutor plugin installation instructions for ``tutor-contrib-owly``.\n",
"bugtrack_url": null,
"license": "AGPL 3.0",
"summary": "One-line description for README and other doc files.",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/aulasneo/openedx-owly-apis"
},
"split_keywords": [
"python",
"edx"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "dd014e9947c94feb94c30b2cd1e419ba402600386b5a23dd5c4f716f36847188",
"md5": "cc6d0347f8bd372025a5bcee147c7474",
"sha256": "fc375e0b62482ef0fe4ef298f6a08b159cbb64e1e5db1d7476e019fc3427dd13"
},
"downloads": -1,
"filename": "openedx_owly_apis-1.0.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "cc6d0347f8bd372025a5bcee147c7474",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.11",
"size": 35536,
"upload_time": "2025-08-27T20:48:16",
"upload_time_iso_8601": "2025-08-27T20:48:16.672639Z",
"url": "https://files.pythonhosted.org/packages/dd/01/4e9947c94feb94c30b2cd1e419ba402600386b5a23dd5c4f716f36847188/openedx_owly_apis-1.0.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "17af04fc920108aff39fe69dfae99b631b65ee6d6e3d559eb282b2a5ef47b444",
"md5": "690ba354dca44de2850d0ecb8113689a",
"sha256": "75a8035f005356c19e13f1d2c8cb5f90f555c6b4014633aabbf5207340b60cd2"
},
"downloads": -1,
"filename": "openedx_owly_apis-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "690ba354dca44de2850d0ecb8113689a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 40327,
"upload_time": "2025-08-27T20:48:18",
"upload_time_iso_8601": "2025-08-27T20:48:18.262054Z",
"url": "https://files.pythonhosted.org/packages/17/af/04fc920108aff39fe69dfae99b631b65ee6d6e3d559eb282b2a5ef47b444/openedx_owly_apis-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-27 20:48:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aulasneo",
"github_project": "openedx-owly-apis",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "openedx-owly-apis"
}
JSON
