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?