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
- :
- GraphQL
- Theming
- Front-end plugins (see Technology Investigations)
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
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?