This article is geared towards individuals intending to set up and work with Open edX REST APIs. It also assumes you already have an Open edX instance set up in the cloud.
What is Open edX?
Open edX is a free and open-source learning management system (LMS) and course authoring platform. It was originally developed by Harvard and MIT to power their Massive Open Online Courses (MOOCs), but it has since been adopted by a wide range of organizations, including universities, businesses, and government agencies.
Open edX is a modular platform, which means that it is made up of several different components that can be combined in different ways to meet the specific needs of each organization. This flexibility makes it a good choice for organizations of all sizes and with a variety of learning needs.
Story Time
Time for a short story as to what inspired me to write this article.
A couple of months ago I took over a software project as the head developer had left the company. I was to link our in-house LMS (Learning Management System) to our e-commerce page.
The user story went like this:
When a customer purchases a course:
they are automatically enrolled into the LMS.
sent an email with details on how to access the LMS and course they just purchased.
The requirements aren't much and simple enough to achieve, at least that's what I thought to myself 😂😂. What followed was 2 weeks of frustration trying to figure out how exactly to achieve this.
The main culprit was Open edX fragmented documentation, poor documentation left behind by the previous developer who I couldn't reach to ask questions and finally my imposter syndrome.
Set up
First things first, check whether you are authenticated as an edX REST Web Service User to be able to access the API catalogue.
In your browser enter the https://<your_openedx_instance_url\>/api-docs and try logging in to see if you are authenticated.
If the page doesn't look like the one below, you are not authenticated.
Client ID & Secret
Since the authentication process is too long to cover in one article follow this guide https://course-catalog-api-guide.readthedocs.io/en/latest/index.html, and come back when you've finished.
It will guide you in Authenticating as a REST API Web user by Open edX.
Upon activation, go to the admin panel of your organization's instance https://<your_openedx_instance_url>/admin/oauth2_provider/ and click "Add Application" in the top left of the page.
This will create for you a new client and secret, you just have to name the application.
The 'client id' and 'client secret' are what are used to get the 'access token'. If you are not familiar with what tokens are here is a good explanation on the Google Clouds page.
The docs don't offer a sandbox to play around with the endpoints unfortunately, this is where Postman come in handy.
Testing API Endpoints
Your unique REST API will be structured this way https://<your-organization-url>/api/user/v1/
To make API calls you need an access token which is generated using the clientId and clientSecretKey.
If you don't know what those are click on the links attached to the words.
We will be using cUrl commands to test our API in Postman.
Below is an unfinished sample, fill in the blanks with your app's unique client id and secret.
curl -L 'https://<your_openedx_instance_url>/oauth2/access_token' \
-d 'client_id=' \
-d 'client_secret=' \
-d 'grant_type=client_credentials'
Upon filling in the blank variables open Postman, click the '+' and paste the cUrl command in full and finally click 'Send.'
The output from the cUrl command is shown below.
Or if you prefer to code the equivalent of the cUrl command.
import requests
# Set your Open edX instance URL and client credentials
openedx_instance_url = 'https://<your_openedx_instance_url>'
client_id = 'your_client_id'
client_secret = 'your_client_secret'
# Define the token endpoint
token_endpoint = f"{openedx_instance_url}/oauth2/access_token"
# Set the payload for the POST request
payload = {
'client_id': client_id,
'client_secret': client_secret,
'grant_type': 'client_credentials'
}
# Make the POST request to obtain the access token
response = requests.post(token_endpoint, data=payload)
if response.status_code == 200:
# Successfully obtained the access token
access_token = response.json().get('access_token')
print(f"Access Token: {access_token}")
else:
# Failed to obtain the access token
print(f"Failed to obtain access token. Status code: {response.status_code}")
print(response.text)
With the access token at hand, you can make API calls to any of the endpoints at your disposal.
Conclusion
Hopefully, you can build incredible stuff with Open edX, the documentation covers only the endpoints but the payloads the endpoints take aren't listed. And this is my biggest gripe with Open edX API, you'll need to look elsewhere and ask the community for help when the payloads you're sending aren't working.
Here are links to resources I used when I encountered a problem:
https://edx-enterprise-api.readthedocs.io/en/latest/index.html
https://course-catalog-api-guide.readthedocs.io/en/latest/index.html
Happy coding!