Documenting APIs

EdX applications present REST web services APIs to provide information about courses and learners, to allow external clients to configure an edX site, and to allow the separate independently deployable applications (IDAs) in an edX site to interact. The edX documentation team covers individual APIs that are supported for external use. Additional APIs are available but may be deprecated or not intended for use by external clients. The following documents include information about edX REST APIs.

• The Open edX Platform APIs guide includes information about the APIs available from the edX platform applications.
• The Open edX Data Analytics API guide includes information about the API for the data analytics application.
• The EdX Course Catalog API User Guide includes information about the Course Catalog API (formerly called the Course Discovery API), which is  available from the course discovery IDA. This documentation is specifically for edx.org users. Although the Course Catalog API is presented by the course discovery IDA, users interact with it through the API manager IDA, which routes REST requests to individual IDAs.

Recent API documentation projects use standard RST content to describe REST resources and response data. The documentation team is exploring ways to use automatically generated API documentation along with manually written content. Some edX IDAs include Swagger API documentation generated from the Django REST Framework implementation of those APIs. The automatically generated API documentation is not intended to indicate support for use by external clients.

Older documentation projects included the Python docstrings for the API implementation as the source of the API documentation. These projects use the Sphinx autodoc extension to include Python docstring content in RST documentation. Autodoc requires that the RST files be in the same repository as the Python API code and it requires that the documentation build process can import all of the Python modules that are used in the API implementation. Importing the Python modules has caused problems during documentation publishing, and in more recent projects, the documentation team has stopped using the autodoc extension.

The EdX XBlock API Guide includes information about the Python API that you can use to build an XBlock component. The XBlock API is not a REST web services API and its documentation is focused on the Python API code.