API Documentation

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.

2016-09-07 Meeting notes: API documentation and testing: Notes from a meeting with Ben Patterson and members of the documentation team about silent build failures in API documentation.

Peter Desjardins AMA Page: Wiki page of questions for Peter Desjardins, who was maintaining our API documentation before his departure in September. There are several items about 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.