2015.02.05 Course APIs

Clinton, Carson, Brandon, Nimisha, Dave O, Miki, Peter, Piotr, Ned, Cale, Ed, Jim, Vishal, Matt

Deltas from last time:

  • stripped out all the content APIs
  • structure is a json object mapping ids to block structure data, children is a list of ids
    • why isn't it hierarchical?
      • flat is more application-agnostic
      • tree might not be general enough, if the course is a dag.
      • even orphans can be listed with a flat structure.
  • authentication hasn't been discussed
    • dedx is moving auth components to a separate repo
  • authorization
    • anyone can look at any course
    • the api will be publicly exposed
    • don't mobile app users have an oauth token?
    • clinton will be dealing with permissions.
    • MUST: be sure an oauth2 token isn't enough to access all courses.

The internal API (a method on modulestore returning JSON) is needed, but isn't meant for wide use

  • MUST: Add to the docstring, explaining all of the downsides, and the appropriate use of this method.

Content versions?

  • This only provides the published version.
    • For analytics, they will need to report on out-of-date content, so versioning must be accommodated somehow.
    • versions have to be exposed throughout the system.

Detail questions:

  • The blocks are in the "blocks" object under their usage key, and then have the key as "id" in the block itself.
  • The blocks have "type", what about "category"?
    • "category" is old, we prefer "blocktype"
  • Why is depth=2 included?
    • oversight, that is going away.
  • Will this be in Birch?
    • no.

Everyone is OK with this going forward.

Course API Unification

  • Not enough detail to code to yet.
  • Dave was trying to flesh out a scheme for layering APIs
  • Content-based vs Discovery-based: did that make sense?
  • Dave: what would be sufficient detail to make a decision?
    • Where do we plugin our API?
    • Guidelines about where an API should live.
    • Everyone wants to know what the whole namespace looks like,
    • and what the rules are for adding to the namespace.
      • for example, "this part of the namespace needs to be highly performant"
    • Guiding principles for API in general.
      • There's a doc growing these guidelines
      • deliverable by the end of this month.
      • bring that to arch council
  • Deployment? Resident in LMS always?
    • API/process is not 1-1
    • Moving more toward a model of process components that host multiple APIs
  • Discovery layer?
    • Yes, we need to think about service discovery.
    • People have floated ideas, but no one has gotten to the point of a proposal.
    • We will favor having small APIs
    • Central discovery will be important, but we don't know enough yet.
    • There will be a number of deployment use cases to solve
      • token storage
      • rate limiting
      • monitoring
  • What does Dave want other people to think about?