API Architecture Landscape

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

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.

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?