Note: The edX platform API documentation strategy is currently under discussion. Currently (11/12/15) we aren't writing documentation for our APIs.

Introduction

APIs are used to get or update information such as the number of bookmarks a user has, a user's account information and preferences, a list of videos in a course, or course updates. For a great tutorial that covers API basics, see Zapier's An Introduction to APIs.

API Documentation

API documentation includes information about what the user can do with the API. Most of this information is presented in the EdX Platform APIs documentation. There is also the data analytics API and the XBlock API.

Note: Platform API documentation is part of the edx-platform repository.

Each API has one or more resources: these are the items that outside users interact with to get the information that they want. Documenting APIs is essentially documenting these resources.

Documentation for an API has at least four files: three .rst files created by the doc team, and a views.py file that the engineering team creates and the doc team edits.

index.rst: Lists the overview file and the resource_name file or files.
overview.rst: Contains information about the current version, status, resources, possible tasks, and endpoints.
resource_name.rst: Contains information about the resource's use case, example requests, response values, and example responses. Most of this information is pulled automatically from the views.py file for that resource. Every resource has its own resource_name.rst file. Example responses should be in the RST file, not the views.py file.
views.py: A Python file that contains the docstrings that must be edited. These docstrings are imported into the resource_name.rst file for the resource. Every resource has its own views.py file.

For example, the Enrollment API has only one resource. For the Enrollment API, documentation consists of the following files.

views.py
index.rst
overview.rst
enrollment.rst

The Mobile API has three separate resources: course_info, users, and video_outlines. Each resource has its own .rst file and its own views.py file. The Mobile API documentation consists of the following files.

index.rst
overview.rst
course_info.rst
course_info/views.py
users.rst
users/views.py
video_outlines.rst
video_outlines/views.py

Step 1: Assemble Information

To document resources, you need two documents. The engineering team creates both of these documents and should let you know where they are.

The views.py file for each resource
The API spec

views.py

Views.py files are always inside a djangoapps/API_Name folder, but the location of that folder varies, and the views.py file will be in a djangoapps/API_Name/Resource_Name folder if the API has multiple resources. Example paths to several different views.py files follow.

edx-platform/lms/djangoapps/mobile_api/course_info/views.py (resource 1 of 3)

edx-platform/lms/djangoapps/mobile_api/users/views.py (resource 2 of 3)

edx-platform/lms/djangoapps/mobile_api/video_outlines/views.py (resource 3 of 3)

edx-platform/openedx/core/djangoapps/user_api/accounts/views.py (resource 1 of 2)

edx-platform/openedx/core/djangoapps/user_api/preferences/views.py (resource 2 of 2)

edx-platform/openedx/core/djangoapps/bookmarks/views.py

edx-platform/openedx/core/djangoapps/profile_images/views.py

edx-platform/common/djangoapps/enrollment/views.py

API specs

These are usually wiki pages. To become acquainted with API specs, see the following documents.

Step 2: Edit the Doc Strings in the views.py File for Each Resource

After you find the views.py file for each resource, you edit the doc string in that file.

For more example API doc strings, see Example API Doc Strings.

In the views.py file for each resource, locate a section that starts with a class and contains the following headings.

Use Case or Use Cases (required)
Example Request or Example Requests (required)
- Method_Name Parameters (optional) (for example, POST Parameters) (there may be more than one of these - for example, there may be GET Parameters and POST Parameters headings)
Response Values (required) (there may be more than one of these - for example, there may be GET Response Values and POST Response Values headings)

This class section is the doc string for the resource. The views.py file may contain more than one class section. When you create the page for the individual resource, you create a heading for each class.

This section may be short, as in the following example, or long.

Code Block

class VideoTranscripts(generics.RetrieveAPIView):
    """

    **Use Case**

        Get a transcript for a specified video and language.

    **Example request**

        GET /api/mobile/v0.5/video_outlines/transcripts/{organization}/{course_number}/{course_run}/{video ID}/{language code}

    **Response Values**

        If the request is successful, the request returns an HTTP 200 "OK"
        response along with an .srt file that you can download.
    """

Edit all of the text in this section, keeping the following guidelines in mind.

...

Step 3: Create the API Folder

For platform API documentation, in the edx-platform/docs/en_us/platform_api/source/ folder, create a folder for the documentation for the API and name the folder the API name, lowercase with underscores instead of spaces. For example, for the Profile Images API, the folder is docs/en_us/platform_api/source/profile_images/.

Step 4. Create the resource_name.rst File for Each Resource

For platform API documentation, in the new edx-platform/docs/en_us/platform_api/source/api_name folder, create an .rst file for each resource. This file will contain the text that you import from the views.py file as well as example responses for the requests that the views.py file describes.

For example resource_name.rst files, see video_outlines.rst File or profile_images.rst File.

...

Code Block

class PreferencesView(APIView):
    """
        **Use Cases**
            Get or update the user's preference information. Updates are only
            supported through merge patch. Preference values of null in a
            patch request are treated as requests to remove the preference.
        **Example Requests**
            GET /api/user/v1/preferences/{username}/
            PATCH /api/user/v1/preferences/{username}/ with content_type "application/merge-patch+json"

The preferences.rst file has the following text.

Code Block

.. _User Preferences API:

##################################################
User Preferences API
##################################################

This page contains information about using the User Preferences API to
complete the following actions.

.. contents::
   :local:
   :depth: 1

.. _Get or Update User Preferences Information:

**************************************************
Get or Update the User's Preferences Information
**************************************************

...

Under the heading for the tasks that are associated with the particular class, use the autoclass directive to import the doc strings that you edited in the views.py file into the resource_name.rst file. To do this, you need three things.

The name of the folder that contains the views.py file.
"views" (without the quotation marks).
The name of the class (without "(APIView)").

Separate these with periods.

Code Block

language	groovy
theme	Eclipse

.. autoclass:: folder_name.views.class_name

For example:

Code Block

language	groovy
theme	Eclipse

.. autoclass:: user_api.preferences.views.PreferencesView

...

Note, again, that each resource must have its own resource_name.rst file.

Step 5: Create the overview.rst File

For platform API documentation, in the edx-platform/docs/en_us/platform_api/source/API_Name folder, create an overview.rst file. There is only one overview.rst file for each API, no matter how many resources the API has.

For example overview.rst files, see overview.rst in Example API .rst Files, overview.rst File in Video Outlines Resource Documentation or overview.rst File in Profile Images API Documentation.

The overview.rst file contains the following sections.

Introduction: A brief statement about the API.
API_Name API Version and Status: A brief statement about the version number. May also include information such as "We plan to make significant enhancements to this API." For a new API, the version number is almost always 1.
API_Name API Endpoints: A table listing the tasks that a user can accomplish with the resources that the API has, along with the methods and endpoints to use. If the API has more than one resource, this heading will be "API_Name Resources and Endpoints", and each resource will have its own subsection with its own Task/Method/Endpoint table.

Information for the "API_Name Endpoints" table comes from the views.py file and the API spec.

In the views.py file, you can find the tasks, methods, and endpoints for each resource from the Use Case and Example Request sections.

The Task is the action listed under "Use Case" (or "Use Cases"). (You used this information when you created the resource_name.rst file for the resource.)
The Method is the verb under "Example Request" (or "Example Requests"). This will typically be GET, PATCH, POST, PUT, or DELETE.
The Endpoint is the text that follows the verb under "Example Request". (It is the last part of a uniform resource locator, or URL, that specifies the location of the resource.) One endpoint may have more than one associated verb.

For example, you might see the following text in the views.py file.

Code Block

class VideoSummaryList(generics.ListAPIView):
    """
    **Use Case**
        Get a list of all videos in the specified course. You can use the
        video_url value to access the video file.
    **Example Request**
        GET /api/mobile/v0.5/video_outlines/courses/{organization}/{course_number}/{course_run}
 
class UserCourseStatus(views.APIView):
    """
    **Use Cases**
        Get or update the ID of the module that the specified user last visited in the specified course.
    **Example Requests**
        GET /api/mobile/v0.5/users/{username}/course_status_info/{course_id}
        PATCH /api/mobile/v0.5/users/{username}/course_status_info/{course_id}

In this case, you would create the following endpoints table.

Task

Method

Endpoint

:ref:`Get a list of all videos in the specified course

 <Get video list>`

GET

/api/mobile/v0.5/video_outlines/courses/{organization}/{course_number}/{course_run}

:ref:`Get the ID of the module that the specified user last visited

in the specified course <Get or update module ID>`

GET

/api/mobile/v0.5/users/{username}/course_status_info/{course_id}

:ref:`Update the ID of the module that the specified user last visited

in the specified course <Get or update module ID>`

PATCH

/api/mobile/v0.5/users/{username}/course_status_info/{course_id}

Note that you can only use the endpoint that appears in the views.py file example request if the example includes placeholders instead of "real" values. If the example request contains non-placeholder values, as in the following example, you can look in the "Endpoints" section of the API spec for the correct endpoint.

Code Block

class EnrollmentListView(APIView, ApiKeyPermissionMixIn):
    """
        **Use Case**

            * Enroll the currently signed in user in a course.
              Currently a user can use this command only to enroll the user in
              honor mode. If honor mode is not supported for the course, the
              request fails and returns the available modes.
              
  			  This command can use a server-to-server call to enroll a user in
              other modes, such as "verified" or "professional". If the mode
              is not supported for the course, the request will fail and
              return the available modes.

        **Example Request**

            POST /api/enrollment/v1/enrollment{"mode": "honor", "course_details":{"course_id": "edX/DemoX/Demo_Course"}}

Step 6: Create the index.rst File

In the edx-platform/docs/en_us/platform_api/source/API_Name folder, create an index.rst file. Include entries for the following files.

overview
API or Resource 1 Name
API or Resource 2 Name (if any)

For more information, see the index.rst examples in Example API .rst Files.

Step 7. Update Source Folder Files

Add entries about the new API to the following files.

docs/en_us/platform_api/source/change_log.rst
docs/en_us/platform_api/source/index.rst
docs/en_us/platform_api/source/overview.rst

Step 8. Update the conf.py File

Update the docs/en_us/platform_api/source/conf.py file.

Often when adding a new module, you need to change to conf.py file in the doc project "mock" other classes that are imported into code. If build has warnings, check with Mark.

Example Files

For examples of complete API documentation in raw form, see Mobile API Documentation and Profile Images API Documentation.

For examples of doc strings in views.py files, see Example API Doc Strings.

For example index.rst and overview.rst files, see Example API .rst Files.

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 API available from the course discovery IDA. This documentation is specifically for edx.org users. Although the 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. In particular, importing the Python modules has caused problems during documentation publishing.

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.

Versions Compared

Old Version 53

New Version 54

Key

Introduction

Step 1: Assemble Information

views.py

API specs

Step 2: Edit the Doc Strings in the views.py File for Each Resource

Step 3: Create the API Folder

Step 4. Create the resource_name.rst File for Each Resource

Step 5: Create the overview.rst File

Step 6: Create the index.rst File

Step 7. Update Source Folder Files

Step 8. Update the conf.py File

Example Files

Page Comparison

Versions Compared

Old Version 53

New Version 54

Key

Introduction

Step 1: Assemble Information

views.py

API specs

Step 2: Edit the Doc Strings in the views.py File for Each Resource

Step 3: Create the API Folder

Step 4. Create the resource_name.rst File for Each Resource

Step 5: Create the overview.rst File

Step 6: Create the index.rst File

Step 7. Update Source Folder Files

Step 8. Update the conf.py File

Example Files