Random notes about where we can make progress on API architecture, with an eye toward outside efforts.  The top-level sections are divided by the type of work needed.

Comments are welcome.  Things might be missing, suggest them.

API Types

Just to establish a vocabulary for the types of APIs we are talking about.

• Existing APIs (users call them):
  • REST
  • Python
  • JavaScript
  • Django signals
  • Feature toggles
• Existing Frameworks (they call users):
  • XBlocks
  • Pluggable Django apps
• Third-party standards
  • xAPI/Caliper
• Future:
  • GraphQL
  • Theming
  • Front-end plugins (see Technology Investigations)
• Out of scope?
  
  • Site configuration

Design Conventions

These need to be written, to provide guidance to API designers and implementors.

• General
  • The Trichotomy 
  • Lifecycle
    • Design
    • Incubation
    • Formalization
    • Evolution
    • Deprecation
      • (how do we discover that something is no longer used?)
  • Support model
• REST APIs
  • Substantive existing writeup is at Open edX REST API Conventions.
  • Versioning
  • Pagination (in-progress by Dave O)
  • Security
  • Naming
  • Parameters
  • Multi-site
  • SLAs and performance goals
  • language-headers
  • Errors (reasonable 4xx and 5xx returns should be happening for each endpoint; useful localizable strings should return as error messages)
• Python APIs
  • (what do we need here?)
  • See Python API ADR for edx-platform
  • Versioning
  • Mock objects for django plugin apps – separate repo?
  • Naming conventions
  • Base functionality requirements: pull from existing plugins (e.g., openedx-completion-aggregator compat, eox-core edxapp_wrapper)

Technology Investigations

Larger areas with some unknowns that have to be fleshed out.

• Front-end plugins
  • how will micro-frontends be extended?
•  Testing
  • for scalability
  • consumer-based contract testing for backward compatibility
• Shielding
  • API gateway
  • Python shim plugin

Coding Conventions

Places where we can provide detailed guidance about how to implement.

• DRF best practices
• Authentication best practice

General Implementation

Implementation work that spans APIs.

• Sample implementations of Coding Conventions best practices
• Documentation tooling
• Best-practice linters
• Testing infrastructure
• API Clients (edx-rest-api-client, edx-api-client, can also be autogenerated)

Specific Implementations

Implementation work on specific APIs

• Clean up of old APIs
• Removal of unused APIs
• Fleshing out documentation of existing APIs
• New APIs!

Open Questions

Things I didn't know where else to put.

• How do we measure how well we are doing against rules/conventions/rubrics/best-practices?
• Metrics: what do we need to do? What work is needed?
• Security: what do we need to do? What work is needed?