Attendees: Nimisha (presenter), Peter Pinch, Matt Drayer, Andy Armstrong, Piotr Mitros, Miki Goyal, Mark Haseltine, Dave Ormsbee (remote), Will Daly (remote), Jim Abramson (remote), Cale Pennington (remote), Steve Magoun

Meta: edx needs an API roadmap - what APIs do we want, what are they for, which ones have been built

Will be hugely valuable for us and our community
Matt tasked with this

Discussion:

Course API

Course Structure API for insights to extract information

Analytics needs access to blocks that no longer exist (think version control)

Instructor vs Student scope

Scope “feels weird"
Can scoping be handled via query?

Proposal gives multiple pathways through the course

Return all pathways vs 1 pathway - do they need different APIs / are they different resources?

Concern about top-level resources based on expected usage:

A researcher might want to use an /instructors endpoint.
Will we put other types of data (not course structure) underneath the /instructor API?
Consensus is that use-case-based resources are not what we want

Alternate proposal

Top-level /courses endpoint, which returns user’s view with optional filtering
Default path would be set to most used endpoint. Pick one for now
Use filter parameters to allow caller to choose how they get data - 1 path? all paths?
Implementation also has to use permissions to filter what the caller sees

Course Blocks

If you call this API and (1) we don’t know the content yet (because it’s dynamic) or (2) the content the hasn’t been published yet, do we tell the user?

User-specific Content

Becomes more complicated as edX matures - for example adaptive learning
Search already handles searching of A/B content and cohort-aware content. Should the system should be consistent in its behavior across search, course API?

Cohort visibility can be pre-calculated, stored in relational table
How do we deal with randomized and other content?

Nimisha working with Cale, others on a performant implementation

Student Views

has_responsive_ui decorator

Cale: want a more generic decorator rather than has_responsive_ui decorator. Proposal - XBlock.View property. Concern: do we have to name all properties and targets (“responsive”). Response: The decorator states that the view is responsive.
What are best-practices around returning content - should we return all content to the client and let the client figure out what to render? Should we limit what we send based on the client?
This decorator seems like an interim thing - assumption is that everything will be responsive in the future
Consideration: touch-enabled vs requires a keyboard.
Proposal: Create new Learner View that is modern, assumes responsive/etc; make Student View legacy.

Tabled

Council advice: we’ve identified multiple attributes we need to care about for mobile.

AI: Nimisha + BrianT to think about what attributes are important - responsive, touch-ready, etc. Document assumptions. Find a way to provide a useful error message “Sorry, this XBlock requires a keyboard”

student_view_json

Data for native rendering
Change to student_data_view (some XBLocks don’t output json)

When would we not want JSON? A small handful of cases (RSS)

block_url

How will it be rendered in the LMS? LMS d/n use iframes. Would prefer to have HTML to embed in the LMS.
AI: Andy + Nimisha to follow up on rendering client view in the LMS, with a goal of being able to use the APIs in the LMS

Steve: consider talking to Xavier (OpenCraft) too for his experience with rendering XBLocks in other UIs

web URL

AI: Piotr talk to Lou about rendering browser views in mobile devices

Course Navigation

Concern about courses with optional content or other “rich” features that should not be exposed to users on mobile devices through primary course navigation path. Needs further discussion. One option is to wrap rich content in a wrapper

AI: Nimisha, Piotr, product to define use cases for rich content

APIs

/api/courses/v1/{course_id{/navigation/ - how do you tell the API where you are?
navigation ad block endpoints are semantically different but implemented the same way
Do we want to allow specifying a particular block to start from, to show subtrees?

McKinsey use case

Can we collapse the course/blocks endpoint into XBlock API endpoint: drop course, and just pass in xblock as starting point

Having distinction of course is helpful for human contemplation of the API

Navigation is course-specific
AI: Nimisha, Matt, Andy to flesh out API endpoints

Browser not supported