API Trichotomy Proposal

Owned by Nimisha Asthagiri (Deactivated)
Last updated: Sept 13, 2021

Here is a proposal for supporting a trichotomy of APIs in the edX platform. The trichotomy defines just-enough maintenance and process that is appropriate for each tier, enabling and balancing developer efficiency with consumer support.


API TypeFeature-driven APIs
(API for development)		Service APIs
(API for extensions and add-ons)		Business-driven APIs
(API as a product)
Use Casefeature developmentfeature enhancementsintegration with strategic organizations and partners
Usersopen edX developerscourse teams, open edX vendor communityadministrators, researchers, institutions
Clientsfrontend and backend servicesexternal servicesexternal systems operated by business-partner organizations
Support Lifecycle1 open edX named release2 years with a migration plan, if API changes2-3 years with a migration plan, if API changes
Governance
  • less governance
  • follows edX API conventions
  • follows OEP process for major APIs
  • high governance on additions/edits
  • business case made for support and development effort
  • follows edX API conventions
  • follows DDD practices on naming
API Examples
  • student dashboard
  • password reset
  • backend-for-frontend payment
  • Real-time Events: xAPI and Caliper
  • Proctoring plugin interface
  • Account retirement hooks
  • Grades
  • Course provision
  • User provision
  • Catalog
Client Examples
  • mobile apps
  • studio frontend
  • enterprise admin portal
  • adaptive engine
  • email provider
  • video conferencing service
  • on-campus SIS
  • corporate reports