SIGN IN SIGN UP

feat: apply ADR 0036 (nested JSON normalization) across 6 standardized APIs (#38773)

* feat: apply ADR 0036 to Xblock v1 (?view=minimal)

Adds a ``?view=minimal`` query parameter on ``XblockViewSet.retrieve``
that filters the (tree-shaped) xblock response down to a small set of
structural fields — id, display_name, category, children, has_children,
studio_url — dropping heavy/contextual fields such as data, metadata,
fields, student_view_data, edited_on, published.

Default response shape is unchanged (full xblock payload) to avoid
breaking the existing Studio frontend. The pre-existing ``?fields=...``
query parameter retains its legacy "type of response" semantics
(?fields=graderType, ?fields=ancestorInfo, ?fields=customReadToken);
ADR 0036's CSV-subset interpretation is deferred to a future API
version to avoid breaking those callers.

Adds 4 regression tests covering: default response untouched, minimal
strips heavy fields, minimal keeps structural fields, minimal is a
no-op for non-dict response bodies (legacy ?fields=graderType path).

* feat: apply ADR 0036 to CourseHome v3 (?fields= on list action)

The v3 ``HomeViewSet.list`` action returns a wide ``StudioHomeSerializer``
payload with ~25 top-level keys (courses, archived_courses, libraries,
allowed_organizations, allowed_organizations_for_libraries, plus Studio
settings). Adds a ``?fields=`` query parameter so clients can request a
subset of those keys explicitly.

The flat-list ``courses`` and ``libraries`` actions are out of scope
(each returns a single-key dict wrapping a list of small items — no
nested or wide structure to filter).

Adds a shared ``apply_field_selection`` helper to ``v3/utils.py`` so
future v3 viewsets can opt into the same convention without
re-implementing it. Adds 2 regression tests: default keeps all keys,
``?fields=courses,libraries`` restricts to exactly those keys.

* docs: audit CourseHome v4 against ADR 0036 (out of scope)

Adds an ADR 0036 entry to ``HomeCoursesViewSet``'s compliance list
explicitly marking this endpoint as out of scope.

Rationale: the v4 home endpoint returns a flat paginated list
governed by ADR 0032 (DefaultPagination 7-field envelope). ADR 0036
excludes flat lists from its ``?view=`` / ``?depth=`` / minimal-by-default
requirements — those apply to tree-shaped responses or wide flat
objects with embedded sub-objects. Each course item is a thin 9-field
record with no nested children, no embedded sub-objects, and no tree
structure to bound.

Per-item ``?fields=`` subset filtering remains a possible follow-up
(would require a dynamic-fields serializer mixin and per-field schema
documentation) but is deferred to keep the v4 contract stable for the
existing Studio frontend.

* feat: apply ADR 0036 to Enrollment v2 (?view=minimal flattens course_details)

Each enrollment record returned by the v2 ``EnrollmentViewSet.list`` and
``EnrollmentRetrieveView.get`` actions embeds a full ``course_details``
sub-object (which itself includes a ``course_modes`` list and other
heavy course-overview fields). Server-to-server callers and AI agents
that only need to know which courses a user is enrolled in shouldn't
have to parse the embedded sub-object on every row.

Adds a ``?view=minimal`` query parameter on both actions that collapses
the embedded ``course_details`` to a single ``course_id`` string. The
enrollment-level fields (``created``, ``mode``, ``is_active``, ``user``)
are preserved. Default response shape is unchanged.

Adds 2 regression tests (mocked, MongoDB-free): default list keeps the
full shape, ``?view=minimal`` collapses each row's course_details to a
flat course_id and the heavy fields are dropped.

* feat: apply ADR 0036 to Course Detail v3 (?view=minimal + ?fields=)

The v3 ``CourseDetailsViewSet.retrieve`` action returns a wide
``CourseDetailsSerializer`` payload with ~40 top-level fields plus a
nested ``instructor_info`` sub-object (instructor names, bios, image
URLs) and a ``learning_info`` long-form list. The default full payload
is preserved; two new opt-in query parameters apply ADR 0036:

  * ``?view=minimal``  drops heavy fields (overview, syllabus,
    description, short_description, instructor_info, learning_info,
    banner_image_name / banner_image_asset_path, video_thumbnail
    assets, license) — leaving only identification (course_id, org,
    run, title, subtitle, language), schedule (start_date, end_date,
    enrollment_start, enrollment_end, certificate_available_date),
    and flags (self_paced, certificates_display_behavior, has_changes).

  * ``?fields=a,b,c``  keeps an explicit CSV subset of top-level keys.
    Composes with ``?view=minimal`` — the preset is applied first,
    then the explicit subset.

Reuses ``apply_field_selection`` from ``v3/utils.py`` (introduced in
the CourseHome v3 commit) so the convention is consistent across v3.

Adds 3 regression tests (mocked, MongoDB-free): default keeps all
fields, ?view=minimal drops the heavy/embedded ones and keeps
identification/schedule/flags, ?fields=course_id,title restricts to
exactly those keys.

* docs: audit AuthorGrading v3 against ADR 0036 (largely out of scope)

Adds an ADR 0036 entry to ``AuthoringGradingViewSet``'s compliance list.

Rationale: the v3 grading response is a single top-level ``graders``
list of small fixed-shape objects (type, min_count, drop_count,
short_label, weight, id) — no tree nesting, no embedded sub-objects,
no ``children`` field, no wide flat object. ``?view=minimal`` and
``?fields=`` would have no fields to drop; the only ADR 0036 concern
that applies is anti-pattern #3 (unbounded child list).

In practice each course has ≤8 graders (Homework, Lab, Exam, etc.)
and the update flow is exercised only by course-authoring staff,
so the real-world payload is always small. The hard cap is enforced
upstream by ``CourseGradingModel.update_from_json``; documented as a
note rather than re-implemented at the view layer.
T
Taimoor Ahmed committed
780ebaf244b9765e8aaeba8a4adb5dd2b6703dbb
Parent: f3e5da0
Committed by Feanil Patel <feanil@axim.org> on 7/29/2026, 2:26:48 PM