Metadata-Version: 2.4
Name: ol-openedx-course-outline-api
Version: 0.1.0
Summary: An Open edX plugin to add API for course outline (modules) for the Learn product page
Author: MIT Office of Digital Learning
License-Expression: BSD-3-Clause
License-File: LICENSE.txt
Requires-Python: >=3.11
Requires-Dist: django>=4.0
Requires-Dist: djangorestframework>=3.14.0
Requires-Dist: edx-django-utils>4.0.0
Requires-Dist: edx-drf-extensions>=10.0.0
Requires-Dist: edx-opaque-keys
Description-Content-Type: text/x-rst

Course Outline API Plugin
=========================

A django app plugin to add a new API to Open edX that returns a course outline summary (one entry
per chapter) for a given course.

Installation
------------

For detailed installation instructions, please refer to the
`plugin installation guide <../../docs#installation-guide>`_.

Installation required in:

* LMS

How To Use
----------

The API supports a GET call to:

- ``<LMS_BASE>/api/ol-course-outline/v0/<course_id>/``

The endpoint is protected by the platform API auth and requires an **admin** user (DRF ``IsAdminUser``).

The successful response for ``http://local.openedx.io:8000/api/ol-course-outline/v0/course-v1:edX+DemoX+Demo_Course/`` would look like:

.. code-block::

    {
        "course_id": "course-v1:edX+DemoX+Demo_Course",
        "generated_at": "2026-03-17T12:34:56Z",
        "modules": [
            {
                "id": "block-v1:edX+DemoX+Demo_Course+type@chapter+block@1414ffd5143b4b5",
                "title": "Example Week 1: Getting Started",
                "effort_time": 121,
                "effort_activities": 1,
                "counts": {
                    "videos": 5,
                    "readings": 3,
                    "problems": 2,
                    "assignments": 1,
                    "app_items": 0
                }
            }
        ]
    }

Notes
-----

- ``generated_at`` is the timestamp when the outline was built (cached responses return the same value).
- ``effort_time`` and ``effort_activities`` come from the platform Effort Estimation transformer via the Blocks API.
- ``counts`` are computed by walking the Blocks API tree under each chapter (staff-only blocks are excluded):
  - ``videos``: blocks with type ``video``
  - ``readings``: blocks with type ``html``
  - ``problems``: blocks with type ``problem``
  - ``assignments``: sequential blocks that are ``graded`` or have a non-empty ``format`` (except ``notgraded``)
  - ``app_items``: leaf blocks that are not ``video``, ``html``, or ``problem`` (and not container types)

Caching
-------

This endpoint caches the full JSON response using Django's configured cache backend.

- **TTL**: configurable via ``OL_COURSE_OUTLINE_API_CACHE_TIMEOUT_SECONDS`` (default: 1 week).
- **Cache key**: ``<prefix>s<schema_version>:<course_key>:<content_version>``.
  - ``prefix`` is configurable via ``OL_COURSE_OUTLINE_API_CACHE_KEY_PREFIX`` (default: ``ol_course_outline_api:outline:v0:``).
  - ``schema_version`` is a plugin constant (bump it when you change the response shape or computation logic).
  - ``content_version`` is ``course.course_version`` when present; otherwise the key uses ``na``.
- **Invalidation**:
  - Publishing a course that updates ``course.course_version`` produces a new cache key, effectively invalidating old entries.

Troubleshooting
---------------

- **Page not found (404)**: ensure the plugin is installed in the LMS and the URLs are registered.
- **Course ID in the URL**: course keys contain ``+``. Use URL-encoded form (``%2B``) when needed, e.g.
  ``/api/ol-course-outline/v0/course-v1:OpenedX%2BDemoX%2BDemoCourse/``.
