2015.11.18 API Gateway Goals

Owned by Ned Batchelder (Deactivated)
Nov 20, 2015
Action Items:
  • Matt and/or Cale will experiment with using a repo of Swagger specs as a collaboration medium
  • Matt will clarify the list of stakeholders
  • Matt will finish the survey of all the IDAs

  • In room: Matt Drayer, Steve McGoun, Gabe, Joel, Peter Pinch, Miki, Piotr, Nimisha, Robert Raposa, Mark Haseltine, Jim Abramson, Cale, Ned, Chris Dodge, Scott Dunn
  • On Hangouts: Felipe, Vishal
  • API project overview:
    • Many attempts so far
    • More stakeholders now
  • API Goals and Requirements
    • shareable with the world via Open edX
      • as distinct from edx.org?
      • yes, at least some of these endpoints will be served by edx.org
    • adhere to edX REST api conventions
    • Stakeholders
      • why are mobile apps called out specially?
        • they have unusual needs
        • their needs has to be accounted for in all APIs.
        • Why "edX mobile apps", rather than just "mobile apps"
      • is it a goal to allow different adopters to enable/disable different endpoints?
        • that could be a feature?
      • what about internal use of the API?
        • case in point: course discovery
        • provides information to external integrations
        • also needs to get information from a bunch of edx services
  • Some API use cases
    • lots of consumers want to show a list of courses
    • other consumers have other needs
    • mcka has many many needs
  • The System
    • what is the system?
    • we have repos that are not made public as open edx
    • we have public repos that are not part of edx.org
    • the system could be:
      • all the repos, or
      • whatever is installed and running in production, or
      • the LMS
  • Cale proposal: the first thing to standardize on would be the external shell of an Open edX installation.
    • miki: be careful not to narrow down the API to only public-facing things
      • we should follow the same guiding principles for internal things only
    • it would be good if the internal APIs could have things in common with the public APIs.
    • nimisha: we aren't the only ones writing IDAs
      • we want to have consistency across their APIs.
    • mark: do we need to solve the internal APIs in parallel with the public APIs, or do they have to be bundled together?
    • ed: things we use work better for others than things that we don't use.
    • cale: lots of the things in the public api are things we want internally
    • cale: github doesn't use its public API facade to implement its browser interface, and that isn't crazy.
    • it was never intended that internal people *had* to use the public API
  • piotr: understanding how xblocks fit into this API will be important.
    • as an author of an xblock, i want to be able to define my own API, not have edX define it.
    • similarly for lots of course-content endpoints
    • some endpoints will be implemented by the system, while others will depend on having the xblock installed.
    • the goal is to allow for new xblocks to be written and be first-class citizens
  • the endpoints in the proposal so far just reflect the existing system
  • nimisha: how will this be extended?
    • matt doesn't want to be the bottleneck in the future
  • mark: this API is for external integrators
  • API design will be based on usual REST principals
    • Matt is sticking to a tight style
    • the current endpoint list needs to be de-duplicated a bit
    • relationships can be two way (courses for a user, users for a course
    • cale: edX REST conventions say flat?
      • nimisha: it says, "not *too* nested"
      • would we be better off having a name for the relationship ("enrollment"), or not?
      • matt: if the relationship has its own attributes, name it. but don't if we don't have to.
    • more than two related things leads to a combinatorial explosion
  • How do we decide who is a reasonable client of this API?
  • Gabe: maybe we should have a guideline for what the resources are, and that would guide us.
  • Nimisha: lots of things to consider: security, performance, etc.
  • jim: are we starting with what we have, or are we building something new?
    • the goal is to define the coherent end state.
    • then we can decide how to get to that state
    • existing APIs will be looked at
  • cale: we should get the other IDAs into the endpoint list to get all perspectives
  • is the wiki page the right tool for the discussion?
    • matt tried swagger, but it's not collaborative
    • cale: maybe a repo full of swagger definitions of an API?
  • Do we agree on the stakeholders for this API?
    • Yes, generalize the statement to "anyone wanting to integrate with Open edX"
  • Do we understand the scope/context of the API?
    • "External parties to integrate with an Open edX installation"
    • mark: external means they go through rate limiters, etc. trusted vs untrusted
    • because we are open-source, even "internal" APIs have to think about backward compatibility.
  • miki: when we are done, will we be able to build edx.org on the public API? Is that a goal
    • matt: that is not a goal for this work, but it could be extended to do that.
  • we agree that this should be a RESTful API.
    • piotr: "loosely"
    • matt: as tight as I can make it.