API Documentation
- Sylvia Pearce (Deactivated)
- Feanil Patel
API documentation covers a small number of the edX APIs. Because edX has not had an overall API strategy, only a few APIs are documented, and the criteria that make documentation mandatory for a specific API are unclear. Additionally, the current API documentation is very fragile and can break anytime a developer adds a module to the edx-platform repository. For the past year, the documentation team has wanted to find an alternative way to publish API documentation. However, because edX doesn't yet have an overall API strategy, the documentation team has halted progress on API documentation work.
Audiences
External clients, IDA users
Products
All
Frequency
API documentation has been published for specific APIs on request from the product or engineering teams. The documentation is not regularly maintained.
Resources
Documenting APIs: A wiki page that describes current and former documentation methods for edX APIs.
Sphinx Autodoc Content: A wiki page with a step-by-step description of the former way of documenting APIs.
edX REST API Conventions: A wiki page in the Architecture space that outlines the conventions to be used for all edX REST APIs.
/wiki/spaces/DOC/pages/113607066: Notes from a meeting with Ben Patterson and members of the documentation team about silent build failures in API documentation.
Tools
API documentation tools have historically used .rst files, Python docstrings together with the Sphinx autodoc extension, GitHub, and ReadTheDocs. For more information, see Documenting APIs and Sphinx Autodoc Content.