/
2015.11.18 API Gateway Goals

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.

Related content

API Trichotomy Proposal
API Trichotomy Proposal
Architecture and Engineering
More like this
Replatforming Runway Plan
Replatforming Runway Plan
Architecture and Engineering
More like this
API Working Group
API Working Group
Open edX Community
More like this
2015.07.01 Course Blocks and Navigation API
2015.07.01 Course Blocks and Navigation API
Architecture and Engineering
More like this
Needed Architecture Investments
Needed Architecture Investments
Architecture and Engineering
More like this
API Thoughts
API Thoughts
Architecture and Engineering
More like this