[DEPR]: Remove HomePageCourses API v1

[BryanttV]

Proposal Date

2025-01-28

Target Ticket Acceptance Date

2025-02-11

Earliest Open edX Named Release Without This Functionality

Ulmo - 2025-10

Rationale

The HomePageCourses API v1 will be replaced by v2, which offers improvements including pagination, filtering, and sorting. As of Sumac, v2 is the default API used to query the course listing from Studio.

Removal

To completely remove the API v1 in edx-platform it’s necessary:

• Remove the URL from the urls.py file.
• Remove the View from the home.py file.
• Remove the View import from the __init__.py file.
• Remove the Serializer from the serializers.py file.
• Remove the Serializer import from the __init__py file.
• Remove the Tests from the test_home.py file.

Also, it's necessary to remove all references to API v1 in the Authoring MFE. This work is in progress:

• refactor: remove references of ENABLE_HOME_PAGE_COURSE_API_V2 frontend-app-authoring#1611

Replacement

API v2 completely replaces API v1. The PRs related to functionality are as follows:

• feat: add paginated HomePageCoursesV2 view with filtering & ordering edx-platform#34173
• feat: add pagination to the HomePageCoursesV2 API edx-platform#34175
• fix: return empty list when no courses are found for request edx-platform#35942

Deprecation

API v1 will be marked as deprecated in the platform code in Teak. This will remain so until Ulmo, where it will be removed.

As the feature toggle to enable/disable API v2 will be removed, API v1 will have an internal change, as it will get the courses summary from CourseOverview.get_all_courses(), which implies that it will not query the courses from Mongo, but from MySQL.

Migration

As of the Sumac release the default API v1 is not being used, the authoring MFE uses API v2. If for some reason you are still using v1 we recommend to start using v2 which was based on the previous one, but with some improvements.

It's important to note that the format of the API v2 response has changed a bit with respect to API v1. Previously, courses and archived_courses were returned in separate lists, now all courses are returned in the courses property. Archived courses contain the is_active property set to false.

Additional Info

No response

Task List

• refactor!: remove ENABLE_HOME_PAGE_COURSE_API_V2 feature toggle edx-platform#36181
• Mark API v1 as deprecated from edx-platform (Teak)
• Remove API v1 from edx-platform (Ulmo)
• Remove API v1 references from frontend-app-authoring (WIP)

[BryanttV]

Hi @mariajgrimaldi @feanil @bradenmacdonald. Could you check this proposal?

[bradenmacdonald]

Removing v1 from the authoring MFE ASAP makes sense. On the platform side, I'm just wondering if we need to mark it as deprecated in Teak and then remove it in the next release, to give API consumers more time to adjust.

[BryanttV]

Thanks for your comment @bradenmacdonald. Yeah, I think it's better to mark the code as deprecated for Teak, and finally, in Ulmo remove it. I can update the proposal, what do you think? @mariajgrimaldi @feanil

[mariajgrimaldi]

Thank you both! I believe removing the usage of V1 from authoring is the most critical task. If that happens for Teak, I agree that we can extend the date to allow more time for adjustments.

@BryanttV: Can we include that as the migration path? We should also give some indications of what to do to migrate from V1 to V2.

[BryanttV]

Hi @mariajgrimaldi, I updated the Deprecation and Migration section. Also, I included the PR related to removal of the feature toggle in the Task List.

[mariajgrimaldi]

@bradenmacdonald @feanil: we created this PR to drop the use of ENABLE_HOME_PAGE_COURSE_API_V2 in edx-platform. These changes remove the option of using the old V1 behavior of getting the courses from Mongo instead of MySQL. Do you think this might be a breaking change for instances with old courses?

In any case, let's let 2U know about this change, considering the work off of the master. FYI @timmc-edx, can you help us tag whoever might be interested in this change?

[timmc-edx]

This is all CMS, right? That would be 2U's TNL team. I'll ask someone to come take a look.

[mariajgrimaldi]

@timmc-edx: yes, it is! Thank you.

[hinakhadim]

Acknowledging on behalf of TNL team