DCAS API Handoff for LMS
Pre-Requisites
Running API Commands relies on:
- A user in EdX
- User privileges
- A Client ID and Client Secret
Firstly, we decide which user we'll use for making API requests and make sure that user exists and is active in Open EdX. This user can either be an actual user (e.g. jsmith@dcas.nyc.gov) or a dummy user (api_admin@example.com). Either is fine, but requests will be tied back to that user and occasionally emails may be sent to that user.
Then we make sure that user has all the privileges they need to do things like enroll/unenroll users from a course. Generally, that means we give them superuser and platform staff access.
Finally, we need a Client ID and Client Secret. These are credentials EdX generates so that our user can make requests from outside the Open EdX system. They should be kept safe.
To generate a Client ID and Client Secret, the user should login to Open EdX and then navigate to [EdX URL]/api-admin and fill out the form to request API Credentials. If the request is approved, the requesting user should navigate back to [Edx URL]/api-admin and fill out a second form.
At this point, the user will be provided their client ID and client Secret. They can always log in and access [EDX URL]/api-admin/status to review these credentials or regenerate them.
General
Request a Bearer Token
About:
A bearer token is required for most API requests. It authenticates the user making the request with the Open EdX LMS.
Request:
curl --location --request POST '[EdX URL]/oauth2/access_token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=[Client ID]' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'token_type=bearer' \
--data-urlencode 'client_secret=[Client Secret]'
Parameters:
Parameter | Description | Example |
---|---|---|
EdX URL | URL of the EdX Instance | https://azudcs-edxltw04.dcas.nycnet |
Client ID | The Client ID Retrieved from 'Pre-Requisites' above | A 40-character random alphanumeric string |
Client Secret | The Client Secret Retrieved from 'Pre-Requisites' above | A 128-character random alphanumeric string |
Note: By default, bearer tokens expire after 10 hours (36000 seconds). Their duration can be extended by an Open EdX admin.
Code changed for DCAS?: No
Sample Output:
Course Details
Get List of Courses
About:
It returns a list of all the courses present in the LMS. It requires Bearer Token authentication.
Request:
curl --location --request GET '[EdX URL]/api/courses/v1/courses/' \
--header 'Authorization: Bearer [Bearer Token]' \
Parameters:
Parameter | Description | Example |
---|---|---|
EdX URL | URL of the EdX Instance | https://azudcs-edxltw04.dcas.nycnet |
Bearer Token | It is used to authenticate the user | A random alphanumeric string of 30-characters |
Code changed for DCAS?: No
Sample Request:
Sample Output:
Get List of Sections, Subsections, or Units in a Course
About:
It returns a list of all the subsections present inside the course. It requires Bearer Token authentication.
Request:
curl --location --request GET '[EdX URL]/api/courses/v1/blocks/?course_id=[CourseID]&username=[username]&depth=all&block_types_filter=sequential' \
--header 'Authorization: Bearer [Bearer Token]' \
Parameters:
Parameter | Description | Example |
---|---|---|
EdX URL | URL of the EdX Instance | https://azudcs-edxltw04.dcas.nycnet |
Bearer Token | It is used to authenticate the user | A random alphanumeric string of 30-characters |
CourseID | The Course ID of which subsections are being requested | course-v1:edX+DemoX+Demo_Course |
username | A username making the request. Results will be limited to what that user has access to. If you want to view all results, make sure the requesting user has platform staff access | admin_user |
depth | The number of subsections requested | A numeric value or 'all' |
Block Types Filter | The type of hierarchy that is to be requested | 'chapter' for retrieving all sections 'sequential' for retrieving all sub-sections 'vertical' for retrieving all units |
Code changed for DCAS?: No
Sample Request:
Get information about a course
About:
It returns the general information about a course. It requires Bearer Token authentication.
Request:
curl --location --request GET '[EdX URL]/api/courses/v1/courses/[Course ID]' \
--header 'Authorization: Bearer [Bearer Token]' \
--header 'Cookie: openedx-language-preference=en'
Parameters:
Parameter | Description | Example |
---|---|---|
EdX URL | URL of the EdX Instance | https://azudcs-edxltw04.dcas.nycnet |
Course ID | Course ID to get the list of enrollment | course-v1:edX+DemoX+Demo_Course |
Bearer Token | It is used to authenticate the user | A random alphanumeric string of 30-characters |
Code changed for DCAS?: No
Sample Request:
Enrollment
Get list of enrollments in a course
About:
It returns a list of all the user enrolled in a course. It requires Bearer Token authentication.
Request:
curl --location --request GET '[EdX URL]/api/enrollment/v1/enrollments?course_id=[Course ID]' \
--header 'Authorization: Bearer [Bearer Token]' \
--header 'Cookie: openedx-language-preference=en'
Parameters:
Parameter | Description | Example |
---|---|---|
EdX URL | URL of the EdX Instance | https://azudcs-edxltw04.dcas.nycnet |
Course ID | Course ID to get the list of enrollment | course-v1:edX+DemoX+Demo_Course |
Bearer Token | It is used to authenticate the user | A random alphanumeric string of 30-characters |
Code changed for DCAS?: No
Sample Request:
Get Enrollments for a User
About:
It returns a list of all the courses in which the user is enrolled. It requires Bearer Token authentication.
Request:
curl --location --request GET '[EdX URL]/api/enrollment/v1/enrollment' \
--header 'Authorization: Bearer [Bearer Token]'
Parameters:
Parameter | Description | Example |
---|---|---|
EdX URL | URL of the EdX Instance | https://azudcs-edxltw04.dcas.nycnet |
Bearer Token | It is used to authenticate the user | A random alphanumeric string of 30-characters |
Code changed for DCAS?: No
Sample Request:
Enroll a User
About:
This command enrolls a single user in a course. It requires that the user exists in Open EdX.
Request:
curl --location --request POST '[EdX URL]/api/enrollment/v1/enrollment?=' \
--header 'Authorization: Bearer [Bearer Token]' \
--header 'Content-Type: application/json' \
--data-raw '{"mode":"honor", "user":"[username]", "course_details":{"course_id": "[Course ID]"}}'
Parameters:
Parameter | Description | Example |
---|---|---|
EdX URL | URL of the EdX Instance | https://azudcs-edxltw04.dcas.nycnet |
Bearer Token | The token authenticating your user with Open EdX | A 30-character random alphanumeric string |
username | The Open EdX username of the user to enroll in the course. | honor |
Course ID | The course ID of the course to enroll the user into | course-v1:edX+DemoX+Demo_Course |
Code changed for DCAS?: Yes
Commit Name: Enroll and Unenroll a non-registered user using API [Added bearer authetication]
Sample Output:
Pre-enroll a user
About:
It enrolls an un-registered user in a course. It requires Bearer Token authentication.
Request:
curl --location --request POST '[EdX URL]/courses/[CourseID]/instructor/api/students_update_enrollment' \
--header 'Referer: [EdX URL]/courses/[CourseID]/instructor' \
--header 'Authorization: Bearer [Bearer Token]' \
--form 'action="enroll"' \
--form 'identifiers=[email]' \
--form 'role="Learner"' \
--form 'auto_enroll="True"' \
--form 'email_students="True"' \
--form 'instructor=[username]'
Parameters:
Parameter | Description | Example |
---|---|---|
EdX URL | URL of the EdX Instance | https://azudcs-edxltw04.dcas.nycnet |
Bearer Token | It is used to authenticate the user | A random alphanumeric string of 30-characters |
CourseID | The Course ID of which subsections are being requested | course-v1:edX+DemoX+Demo_Course |
Action | The action to take against a user | 'enroll' to enroll the user in the course 'unenrol' to un-enroll a user from the course |
Identifiers | The email of the user to enroll in the course | learner@example.com |
Role | The role to enroll as in the course | 'Learner' to enroll as a learner in the course Other options include 'Support' and 'Partner' |
Auto Enroll | The type of hierarchy that is to be requested | 'chapter' for retrieving all sections 'sequential' for retrieving all sub-sections 'vertical' for retrieving all units |
Email Students | Whether to inform the user via email or not | Either 'True' or 'False' |
Instructor | The username of the instructor who is enrolling the student | admin_user |
Code changed for DCAS?: Yes
Commit Name: Enroll and Unenroll a non-registered user using API [Added bearer authetication]
Sample Request:
Sample Output:
Enroll a Staff
About:
It enrolls a staff users in a course. It requires Bearer Token authentication.
Request:
curl --location --request POST '[EdX URL]/courses/[CourseID]/instructor/api/modify_access_mobile' \
--header 'Authorization: Bearer [Bearer Token]' \
--header 'Cookie: openedx-language-preference=en' \
--form 'unique_student_identifier=[username_to_enroll]' \
--form 'rolename="staff"' \
--form 'action="allow"' \
--form 'instructor=[username]'
Parameters:
Parameter | Description | Example |
---|---|---|
EdX URL | URL of the EdX Instance | https://azudcs-edxltw04.dcas.nycnet |
Bearer Token | It is used to authenticate the user | A random alphanumeric string of 30-characters |
CourseID | The Course ID of which subsections are being requested | course-v1:edX+DemoX+Demo_Course |
Action | The action to take against a user | 'allow' to enroll the user in the course as staff |
Unique Student Identifier | The username of the user to enroll in the course as staff | staff |
Role | The role to enroll as in the course | 'staff' to enroll as a staff in the course. |
Instructor | The username of the instructor who is enrolling the student | admin_user |
Code changed for DCAS?: Yes
Commit Name: New Mobile API to enroll/unenroll a staff user
Sample Request:
Sample Output:
Bulk Enroll Users
About:
It enrolls a bulk users in a course. It requires Bearer Token authentication.
Request:
curl --location --request POST '[EdX URL]/courses/[CourseID]/instructor/api/students_update_enrollment' \
--header 'Referer: [EdX URL]/courses/[CourseID]/instructor' \
--header 'Authorization: Bearer [Bearer Token]' \
--form 'action="enroll"' \
--form 'identifiers="[email_id_01]
[email_id_02]"' \
--form 'role="Learner"' \
--form 'auto_enroll="True"' \
--form 'email_students="True"' \
--form 'instructor=[username]'
Parameters:
Parameter | Description | Example |
---|---|---|
EdX URL | URL of the EdX Instance | https://azudcs-edxltw04.dcas.nycnet |
Bearer Token | It is used to authenticate the user | A random alphanumeric string of 30-characters |
CourseID | The Course ID of which subsections are being requested | course-v1:edX+DemoX+Demo_Course |
Action | The action to take against a user | 'enroll' to enroll the user in the course 'unenrol' to un-enroll a user from the course |
Identifiers | The email IDs of all the users to enroll in the course | learner@example.com |
Role | The role to enroll as in the course | 'Learner' to enroll as a learner in the course Other options include 'Support' and 'Partner' |
Auto Enroll | The type of hierarchy that is to be requested | 'chapter' for retrieving all sections 'sequential' for retrieving all sub-sections 'vertical' for retrieving all units |
Email Students | Whether to inform the user via email or not | Either 'True' or 'False' |
Instructor | The username of the instructor who is enrolling the student | admin_user |
Code changed for DCAS?: Yes
Commit Name: Enroll and Unenroll a non-registered user using API [Added bearer authetication]
Sample Request:
Sample Output:
Unenroll a User
About:
It unenrolls a user in a course. It requires Bearer Token authentication.
Request:
curl --location --request POST '[EdX URL]/courses/[CourseID]/instructor/api/students_update_enrollment' \
--header 'Referer: [EdX URL]/courses/[CourseID]/instructor' \
--header 'Authorization: Bearer [Bearer Token]' \
--form 'action="unenroll"' \
--form 'identifiers=[email]' \
--form 'role="Learner"' \
--form 'auto_enroll="True"' \
--form 'email_students="True"' \
--form 'instructor=[username]'
Parameters:
Parameter | Description | Example |
---|---|---|
EdX URL | URL of the EdX Instance | https://azudcs-edxltw04.dcas.nycnet |
Bearer Token | It is used to authenticate the user | A random alphanumeric string of 30-characters |
CourseID | The Course ID of which subsections are being requested | course-v1:edX+DemoX+Demo_Course |
Action | The action to take against a user | 'enroll' to enroll the user in the course 'unenrol' to un-enroll a user from the course |
Identifiers | The email IDs of all the users to enroll in the course | learner@example.com |
Role | The role to enroll as in the course | 'Learner' to enroll as a learner in the course Other options include 'Support' and 'Partner' |
Auto Enroll | The type of hierarchy that is to be requested | 'chapter' for retrieving all sections 'sequential' for retrieving all sub-sections 'vertical' for retrieving all units |
Email Students | Whether to inform the user via email or not | Either 'True' or 'False' |
Instructor | The username of the instructor who is enrolling the student | admin_user |
Code changed for DCAS?: Yes
Commit Name: Enroll and Unenroll a non-registered user using API [Added bearer authetication]
Sample Request:
Sample Output:
Unenroll a pre-enrollment
About:
It un-enrolls an un-registered user in a course. It requires Bearer Token authentication.
Request:
curl --location --request POST '[EdX URL]/courses/[CourseID]/instructor/api/students_update_enrollment' \
--header 'Referer: [EdX URL]/courses/[CourseID]/instructor' \
--header 'Authorization: Bearer [Bearer Token]' \
--form 'action="unenroll"' \
--form 'identifiers=[email]' \
--form 'role="Learner"' \
--form 'email_students="True"' \
--form 'instructor=[username]'
Parameters:
Parameter | Description | Example |
---|---|---|
EdX URL | URL of the EdX Instance | https://azudcs-edxltw04.dcas.nycnet |
Bearer Token | It is used to authenticate the user | A random alphanumeric string of 30-characters |
CourseID | The Course ID of which subsections are being requested | course-v1:edX+DemoX+Demo_Course |
Action | The action to take against a user | 'enroll' to enroll the user in the course 'unenrol' to un-enroll a user from the course |
Identifiers | The email of the user to enroll in the course | learner@example.com |
Role | The role to enroll as in the course | 'Learner' to enroll as a learner in the course Other options include 'Support' and 'Partner' |
Auto Enroll | The type of hierarchy that is to be requested | 'chapter' for retrieving all sections 'sequential' for retrieving all sub-sections 'vertical' for retrieving all units |
Email Students | Whether to inform the user via email or not | Either 'True' or 'False' |
Instructor | The username of the instructor who is enrolling the student | admin_user |
Code changed for DCAS?: Yes
Commit Name: Enroll and Unenroll a non-registered user using API [Added bearer authetication]
Sample Request:
Sample Output:
Unenroll a Staff
About:
It unenrolls a staff users in a course. It requires Bearer Token authentication.
Request:
curl --location --request POST '[EdX URL]/courses/[CourseID]/instructor/api/modify_access_mobile' \
--header 'Authorization: Bearer [Bearer Token]' \
--header 'Cookie: openedx-language-preference=en' \
--form 'unique_student_identifier=[username_to_unenroll]' \
--form 'rolename="staff"' \
--form 'action="revoke"' \
--form 'instructor=[username]'
Parameters:
Parameter | Description | Example |
---|---|---|
EdX URL | URL of the EdX Instance | https://azudcs-edxltw04.dcas.nycnet |
Bearer Token | It is used to authenticate the user | A random alphanumeric string of 30-characters |
CourseID | The Course ID of which subsections are being requested | course-v1:edX+DemoX+Demo_Course |
Action | The action to take against a user | 'revoke' to unenroll the user in the course as staff |
Unique Student Identifier | The username of the user to unenroll in the course as staff | staff |
Role | The role to enroll as in the course | 'staff' to enroll as a staff in the course. |
Instructor | The username of the instructor who is enrolling the student | admin_user |
Code changed for DCAS?: Yes
Commit Name: New Mobile API to enroll/unenroll a staff user
Sample Request:
Sample Output:
Bulk Unenroll Users
About:
It unenrolls bulk users in a course. It requires Bearer Token authentication.
Request:
curl --location --request POST '[EdX URL]/courses/[CourseID]/instructor/api/students_update_enrollment' \
--header 'Referer: [EdX URL]/courses/[CourseID]/instructor' \
--header 'Authorization: Bearer [Bearer Token]' \
--form 'action="unenroll"' \
--form 'identifiers="[email_id_01]
[email_id_02]"' \
--form 'role="Learner"' \
--form 'auto_enroll="True"' \
--form 'email_students="True"' \
--form 'instructor=[username]'
Parameters:
Parameter | Description | Example |
---|---|---|
EdX URL | URL of the EdX Instance | https://azudcs-edxltw04.dcas.nycnet |
Bearer Token | It is used to authenticate the user | A random alphanumeric string of 30-characters |
CourseID | The Course ID of which subsections are being requested | course-v1:edX+DemoX+Demo_Course |
Action | The action to take against a user | 'enroll' to enroll the user in the course 'unenrol' to un-enroll a user from the course |
Identifiers | The email IDs of all the users to enroll in the course | learner@example.com |
Role | The role to enroll as in the course | 'Learner' to enroll as a learner in the course Other options include 'Support' and 'Partner' |
Auto Enroll | The type of hierarchy that is to be requested | 'chapter' for retrieving all sections 'sequential' for retrieving all sub-sections 'vertical' for retrieving all units |
Email Students | Whether to inform the user via email or not | Either 'True' or 'False' |
Instructor | The username of the instructor who is enrolling the student | admin_user |
Code changed for DCAS?: Yes
Commit Name: Enroll and Unenroll a non-registered user using API [Added bearer authetication]
Sample Request:
Sample Output:
Grades
Get Course Grades for all users in a course
About:
It returns a list of all the users enrolled and their grades in the course. It requires Bearer Token authentication.
Request:
curl --location --request GET '[EdX URL]/api/grades/v1/courses/[CourseID]/' \
--header 'Authorization: Bearer [Bearer Token]'
Parameters:
Parameter | Description | Example |
---|---|---|
EdX URL | URL of the EdX Instance | https://azudcs-edxltw04.dcas.nycnet |
Bearer Token | It is used to authenticate the user | A random alphanumeric string of 30-characters |
CourseID | The Course ID of which subsections are being requested | course-v1:edX+DemoX+Demo_Course |
Code changed for DCAS?: No
Sample Output:
Get Course Grade for a single user
About:
It returns the grades for the user in the particular course. It requires Bearer Token authentication.
Request:
curl --location --request GET '[EdX URL]/api/grades/v1/courses/[CourseID]/?username=[username]' \
--header 'Authorization: Bearer [Bearer Token]'
Parameters:
Parameter | Description | Example |
---|---|---|
EdX URL | URL of the EdX Instance | https://azudcs-edxltw04.dcas.nycnet |
Bearer Token | It is used to authenticate the user | A random alphanumeric string of 30-characters |
CourseID | The Course ID of which subsections are being requested | course-v1:edX+DemoX+Demo_Course |
username | The username of the learner user whose grades are requested | learner_user |
Code changed for DCAS?: No
Sample Output:
Get Section Grade
About:
It returns the grades for the user in the particular section of the course. It requires Bearer Token authentication.
Request:
curl --location --request GET '[EdX URL]/api/grades/v1/subsection/[BlockID]?user_id=[UserID]' \
--header 'Authorization: Bearer [Bearer Token]'
Parameters:
Parameter | Description | Example |
---|---|---|
EdX URL | URL of the EdX Instance | https://azudcs-edxltw04.dcas.nycnet |
Bearer Token | It is used to authenticate the user | A random alphanumeric string of 30-characters |
BlockID | The Block ID of which grades are being requested | block-v1:edX+DemoX+Demo_Course+type@sequential+block@edx_introduction |
UserID | The User ID of the learner user whose grades are requested | 10 |
Code changed for DCAS?: No
Sample Output:
Get User Gradebook
About:
It returns the list of gradebooks for the users enrolled in the particular course. It requires Bearer Token authentication.
Request:
curl --location --request GET '[EdX URL]/api/grades/v1/gradebook/[CourseID]/' \
--header 'Authorization: Bearer [Bearer Token]'
Parameters:
Parameter | Description | Example |
---|---|---|
EdX URL | URL of the EdX Instance | https://azudcs-edxltw04.dcas.nycnet |
Bearer Token | It is used to authenticate the user | A random alphanumeric string of 30-characters |
CourseID | The Course ID of which subsections are being requested | course-v1:edX+DemoX+Demo_Course |
Code changed for DCAS?: No
Sample Output:
User
Get User's Public Information
About:
It returns the all the public information for a particular user. It requires Bearer Token authentication.
Request:
curl --location --request GET '[EdX URL]/api/user/v1/accounts?email=[email]' \
--header 'Authorization: Bearer [Bearer Token]'
Parameters:
Parameter | Description | Example |
---|---|---|
EdX URL | URL of the EdX Instance | https://azudcs-edxltw04.dcas.nycnet |
Bearer Token | It is used to authenticate the user | A random alphanumeric string of 30-characters |
The email of the user of whose information is requested | test@example.com |
Code changed for DCAS?: No
Sample Output:
Update a User's Information
About:
It updates the information of the User whose username is passed in the URL and returns all the public information for a that user. It requires Bearer Token authentication. You can change the values of the following through this API:
- account_privacy
- profile_image
- username
- bio
- course_certificates
- country
- date_joined
- language_proficiencies
- level_of_education
- social_links
- time_zone
- accomplishments_shared
- name
- extended_profile
- gender
- state
- goals
- is_active
- mailing_address
- requires_parental_consent
- secondary_email
- secondary_email_enabled
- year_of_birth
- phone_number
- guid
- first_name
- last_name.
Request:
curl --location --request PATCH '[EdX URL]/api/user_extra_info/v1/update/[username]/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer [Bearer Token]' \
--data-raw '{
"guid":[new_guid]
}'
Parameters:
Parameter | Description | Example |
---|---|---|
EdX URL | URL of the EdX Instance | https://azudcs-edxltw04.dcas.nycnet |
Bearer Token | It is used to authenticate the user | A random alphanumeric string of 30-characters |
username | The username of the user whose email is to be changed | course-v1:edX+DemoX+Demo_Course |
GUID | The new GUID of the user that is to be saved | A random alphanumeric string of 30-characters |
Code changed for DCAS?: Yes
Commit Name: Modified User Information Update API to update and return first_name and last_name
Sample Output:
Provision a new user
About:
This command creates a new user.
Request:
curl --location --request POST '[EdX URL]/user_api/v1/account/registration/?=' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'username=[username]' \
--data-urlencode 'name=[name]' \
--data-urlencode 'email=[email]' \
--data-urlencode 'password=[password]' \
--data-urlencode 'terms_of_service=true' \
--data-urlencode 'honor_code=true' \
--data-urlencode 'country=[country_code]' \
--data-urlencode 'training_id=[training_id]'
Parameters:
Parameter | Description | Example |
---|---|---|
EdX URL | URL of the EdX Instance | https://azudcs-edxltw04.dcas.nycnet |
Username | The username of the new user | new_user |
Name | The name of the new user | New User |
The email of the new user | test@example.com | |
Password | The password of the new user | test123 |
Country Code | The country code of the new user | US |
Training ID | The training of the new user | 1 |
Code changed for DCAS?: No
Sample Output:
Create the SSO link of new user
About:
This command creates a the SSO link of the user with NYCID.
Request:
curl --location --request POST '[EdX URL]/api/dcas_social_auth/[username]/[guid]/' \
--header 'Authorization: Bearer [Bearer Token]'
Parameters:
Parameter | Description | Example |
---|---|---|
EdX URL | URL of the EdX Instance | https://azudcs-edxltw04.dcas.nycnet |
Username | The username of the new user | new_user |
GUID | The GUID of the new user | A random alphanumeric string of 30-characters |
Bearer Token | It is used to authenticate the user | A random alphanumeric string of 30-characters |
Code changed for DCAS?: Yes
Commit Name: Created new app dcas_social_login for the API to create SSO link entry in the usersocialauth table
Sample Output:
Login a User
Deactivate a user
About:
It removes the password of the User whose username is passed in the URL so that User can not log-in/register again. It requires Bearer Token.
Request:
curl --location --request POST '[EdX URL]/api/user/v1/accounts/[username]/deactivate/' \
--header 'Authorization: Bearer [Bearer Token]'
Parameters:
Parameter | Description | Example |
---|---|---|
EdX URL | URL of the EdX Instance | https://azudcs-edxltw04.dcas.nycnet |
Bearer Token | It is used to authenticate the user | A random alphanumeric string of 30-characters |
Username | The username of the user to be deactivated | user_name |
Code changed for DCAS?: Yes
Commit Name: Add bearer token in Retirement API
Sample Output:
Course Export
Export a Course via API
[To Be built]