2015.07.01 Course Blocks and Navigation API

Owned by Steve Magoun (Deactivated)
Last updated: Jul 13, 2015 by Nimisha Asthagiri (Deactivated)
3 min read

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