Epic: Learning Resources & Search APIs

ChristopherChudzicki commented 11 months ago

As a developer, I want to use APIs to explore MIT's open educational resources.

Description

This epic captures remaining work to expose learning resources & learning resource search APIs—the public interface into our resource models. Our APIs should have a convenient and consistent structure and be accurately documented.

API Reference Docs: https://mit-open-rc.odl.mit.edu/api/v1/schema/redoc/

Acceptance Criteria:

### Tasks
- [ ] https://github.com/mitodl/mit-open/issues/146: The search API supports passing multiple values to a single filter parameter. It would be nice for other APIs to support this as well.
- [ ] https://github.com/mitodl/mit-open/issues/110 Convert the search API from a POST request to GET request with simple query parameters & document it.
- [ ] https://github.com/mitodl/mit-open/issues/148 Make search API urls more readable
- [ ] https://github.com/mitodl/mit-open/issues/149
- [ ] https://github.com/mitodl/mit-open/issues/96 Store "certification" as boolean rather than a computed string and allow filtering by it in APIs

Out of Scope

ETL pipelines

ChristopherChudzicki commented 11 months ago

The following question came up in discussion with @Ferdi @mbertrand @abeglova today:

Question: Should the catalog listing and search APIs be unified?

We currently expose several APIs that list learning resources and are filterable:

Catalog APIs:: /api/v1/learning_resources/, /api/v1/courses/, /api/v1/videos/, etc.
Search API:: /api/v1/search/

From an end-user perspective, the Catalog and Search APIs are similar in many regards: both are paginated with limit-offset, both include arrays of LearningResource objects in their result, and both are filterable on many properties. The Search API provides additional functionality in that it can perform textual searches, including on course content.

Note: Among learning resources, LearningPaths are unique in that they are editable by some users. The /learningpath/ endpoints support CRUD and are clearly needed. No other learning resource endpoints support CRUD.

Why would an API end-user ever choose to use a Catalog listing API rather than the Search API? Setting aside LearningPaths.

Cons of Separate `/learning_resources/`, `/courses/`, `/search` APIs

Drift in API request interface. For example, the catalog APIs use ordering for sorting whereas the search API uses sortby.
Drift in API response interface. Minimal risk here. Data is loaded into OpenSearch using the same serializer as catalog APIs.
User needs to pick one. Why?

Cons of Separate `/learning_resources/`, `/courses/`, `/search` APIs

Performance is a potential con: querying the database is faster than querying OpenSearch. However, a unified API could delegate to database / opensearch depending on parameters.

Additional Questions

Can the /learning_resources/upcoming/ and /learning_resources/new/ endpoints be emulated the search?

mbertrand commented 11 months ago

I'd be in favor of using the catalog API endpoint primarily for communication between front and back end where needed (such as learning path CRUD, maybe favorites), as we traditionally do with our app API's. Search API endpoint seems like the better candidate for external use (in addition to driving the search frontend).

sovsey commented 2 months ago

@ChristopherChudzicki @mbertrand @abeglova Are we good to close this epic? It looks like the associated tasks have either been completed or the issues have been archived. Let me know!

ChristopherChudzicki commented 2 months ago

I think closing this makes sense.

mitodl / mit-open