2015.11.18 API Gateway Goals

Action Items:

• 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.