refactor: make CCX Coach v2 API URLs conform to ADR 0038 (remove verbs from create_ccx and remove_schedule)

Đang mở
#39,135 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
35/100
Loại issue
Tái cấu trúc
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
python, typescript

Hướng nghiên cứu

Start with docs/decisions/0038-standardize-rest-api-url-structure.rst and review the existing endpoint changes from #39031 and #39126, then inspect src/ccxCoach/data/api.ts. Resolve the target resource shapes before adding trailing-slash routes, preserving and deprecating released paths, updating the frontend, and covering old and new addresses in tests.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

Description

The CCX Coach v2 API has two endpoints whose paths contain verbs, which violates
ADR 0038 "Standardize REST API URL Structure"
(Accepted 2026-08-12), rule 10: "Resource paths contain no verbs. An operation is a POST to a noun."

Current state of /api/ccx_coach/v2/:

Method Path ADR 0038 status
GET /courses/{course_id}/metadata conforms (noun), but no trailing slash (rule 6)
POST /courses/{course_id}/create_ccx verb in path (rule 10) + no trailing slash (rule 6)
GET / PUT /courses/{ccx_course_id}/schedule conforms (noun), but no trailing slash (rule 6)
POST /courses/{ccx_course_id}/remove_schedule verb in path (rule 10) + no trailing slash (rule 6)

The schedule endpoint was already consolidated onto a single noun in #39126:
the write moved from POST .../save_schedule to PUT .../schedule, since the
body is the complete schedule tree and the operation is an idempotent
full-representation replacement. This issue covers the two remaining verbs plus
the trailing-slash rule.

Proposed changes

1. create_ccx → a noun collection. A CCX is a resource being created, so
creation should be a POST to the collection:

POST /api/ccx_coach/v2/courses/{course_id}/ccx/     (or a top-level /api/ccx_coach/v2/ccx/)

Per rule 8 (hierarchy capped at one level, parent in the query string where the
child is independently addressable) a top-level ccx/ collection with
?course_key= may be the better shape, since a CCX is addressable by its own
opaque ccx-v1: key. Needs a decision during refinement.

2. remove_schedule → express removal on the schedule resource. Options:

  • Fold it into the existing PUT .../schedule, since a full-tree replacement
    already expresses "this block is hidden" — the separate endpoint may be
    redundant. (The MFE's remove flow marks blocks hidden client-side.)
  • Or address the block as a member of the schedule:
    DELETE /api/ccx_coach/v2/courses/{ccx_course_id}/schedule/{location}/
    (rule 9 permits opaque usage keys as identifiers).

3. Trailing slashes. Rule 6 requires exactly one address per route with a
required trailing slash. All four routes currently omit it.

Constraint: metadata and create_ccx are already released

These shipped in #39031, so they cannot simply be renamed. The ADR's
Consequences section requires that "Existing endpoints are migrated under
OEP-21 and never broken"
: mount the new path, mark the old one
deprecated: true in the OpenAPI schema, file a DEPR issue, and keep both for
the deprecation window.

Note also the ADR's warning that unsafe methods sent to a slashless path fail
rather than redirect
under APPEND_SLASH, so the frontend must update paths
rather than rely on a redirect.

remove_schedule is the cheaper half: if it is addressed before the frontend
wires to it, it needs no deprecation window.

Supporting information

  • ADR: docs/decisions/0038-standardize-rest-api-url-structure.rst (rules 6, 8, 9, 10)
  • Related ADRs: 0031-merge-similar-endpoints, 0037-api-versioning-strategy
  • Introduced by: #39031 (metadata + create_ccx), #39126 (schedule endpoints)
  • Epic: #38982 (CCX Coach Conversion to MFE - New Endpoints)
  • Frontend consumer: openedx/frontend-app-instructor-dashboard (src/ccxCoach/data/api.ts)

Acceptance criteria

  • Decide the target shape for CCX creation and schedule-block removal (above).
  • New ADR-conforming routes added, with trailing slashes.
  • Old create_ccx (and metadata, for the trailing slash) kept working, marked deprecated in the OpenAPI schema, with a DEPR issue filed per OEP-21.
  • remove_schedule migrated without a deprecation window if the frontend has not yet adopted it.
  • Frontend src/ccxCoach/data/api.ts updated to the new paths.
  • Tests cover both old and new addresses during the deprecation window.
Ngôn ngữ chính
Python
Star
8.2k
Fork
4.4k
Merge trung bình
2 ngày 10 giờ
Pull request đã merge (30 ngày)
40

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của openedx/openedx-platform

Tất cả issue của openedx/openedx-platform

Issue tương tự

Thêm issue về Python

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.