edapi

This package is an (unofficial) integration of the Ed API with Python. Since as of now there is no detailed documentation on the HTTP endpoints for the Ed API, I've reverse-engineered the endpoints by snooping through Chrome devtools.

Further, since the Ed API is in beta, the API endpoints can change at any time, and this package may break.

This package is still a work in progress, and currently contains the following features:

Authenticating through an Ed API token (accessible through https://edstem.org/us/settings/api-tokens)
Creating threads
Editing existing threads (both through global ids and through course-specific ids)
Uploading files to Ed (through direct file upload)
Get user information
List existing threads

This list may expand as the package is developed further.

Installation

This package is uploaded to PyPI: https://pypi.org/project/edapi/; the easiest way to install is with pip3 install edapi.

Building the package

You can also build the package manually; to do so, just run python3 -m build in the root directory. This will create a dist/ folder containing the package wheel, which can be installed via pip3 install dist/edapi-x.x.x-py3-none.whl.

Documentation

Most documentation can be found in edapi/docs/api_docs.md; it contains documentation for the API, and also several notes on the HTTP endpoints as I've worked through this package.

Usage

The bare minimum to utilize the API integration is to create a .env file in your project storing your API key, or store the API key in an environment variable in an equivalent manner:

ED_API_TOKEN=your-token-here

Your API key can be created through https://edstem.org/us/settings/api-tokens. The API key should be kept secret, and not committed through any version control system.

The following snippet is an example of using the API:

from edapi import EdAPI

# initialize Ed API
ed = EdAPI()
# authenticate user through the ED_API_TOKEN environment variable
ed.login()

# retrieve user information; authentication is persisted to next API calls
user_info = ed.get_user_info()
user = user_info['user']
print(f"Hello {user['name']}!")

Types for all methods are also documented and type hints are used for every method. You can peruse the types in edapi/edapi/types/.

Working with thread content

Ed uses a special XML format to format thread bodies. The various tags are also documented in edapi/docs/api_docs.md for your reference.

There are utility methods included to help with the process of creating thread documents through BeautifulSoup:

new_document(): creates a new blank document containing the bare XML tags necessary to create a new thread.
- Returns a new BeautifulSoup instance for the new document, along with the root document tag (use the document tag to serialize for the API).
parse_document(content: str): parses the content string, which holds the XML content of a thread.
- Similar to new_document, returns a new BeautifulSoup instance for the parsed document, along with the root document tag.

smartspot2 / edapi