README.rst

REST API Client for Open edX

The REST API client for Open edX REST API allows users to communicate with various edX REST APIs. It is based on https://github.com/edx/edx-rest-api-client, whith a few differences:

• It does not depend on Django
• What is called 'the client' in edX's version is now called 'session'.
• As the edX's version relies on Django's cache, now the token is stored in memory under the scope of the session object
• The client here encompasses the session, and one function per REST API entry point

Part of the code is also taken from Opencraft's implementation of the openedx client.

Testing

$ make validate

Usage

The OpenedxRESTAPIClient object starts a session with the LMS and provides methods to access the Open edX endpoints.

# create client
client = OpenedxRESTAPIClient('https://lms.example.com', 'client_id', 'client_secret')

# get a list of all courses
courses = client.list_all_courses()

Function Reference

list_all_courses

Get the full list of courses visible to the requesting user. Calls the /api/courses/v1/courses LMS endpoint

Args:

• org: filter by organization

Returns:

• List of dict in the form:

[
   {
      "blocks_url": "https://lms.example.com/api/courses/v1/blocks/?course_id=course-v1%3A<org>%2B<code>%2B<edition>",
      "effort":"01:00",
      "end":"None",
      "enrollment_start":"None",
      "enrollment_end":"None",
      "id":"course-v1:<org>+<code>+<run>",
      "media":{
         "course_image":{
            "uri":"<img path>"
         },
         "course_video":{
            "uri":"None"
         },
         "image":{
            "raw":"<img url>",
            "small":"<img url>",
            "large":"<img url>"
         }
      },
      "name":"Course name",
      "number":"<edition>",
      "org":"<org>",
      "short_description":"",
      "start":"2018-01-11T00:00:00Z",
      "start_display":"11 de Enero de 2018",
      "start_type":"timestamp",
      "pacing":"instructor",
      "mobile_available":true,
      "hidden":false,
      "invitation_only":false,
      "course_id":"course-v1:<org>+<code>+<edition>"
   },
   ...
]

change_enrollment

Enroll or unenroll (depending on the value of action) the list of emails in the list of courses. Calls the /api/bulk_enroll/v1/bulk_enroll/ LMS endpoint

Args:

• emails: list of emails to enroll
• courses: list of course ids to enroll
• action: can be 'enroll' or 'unenroll'
• url: url of the LMS (base or site). If not specified, uses the base url of the session. Defaults to the LMS base.
• auto_enroll: if true, the users will be automatically enrolled as soon as they register. Defaults to true.
• email_students: if true, an email will be sent with the update. Defaults to true.
• cohorts: List of cohort names to add the students to.

Returns:

dict in the form:

{
   "action":"enroll",
   "courses":{
      "course-v1:ORG+CODE+EDITION":{
         "action":"enroll",
         "results":[
            {
               "identifier":"[email protected]",
               "after":{
                  "enrollment":true,
                  "allowed":false,
                  "user":true,
                  "auto_enroll":false
               },
               "before":{
                  "enrollment":false,
                  "allowed":false,
                  "user":true,
                  "auto_enroll":false
               }
            },
            ...
         ],
         "auto_enroll":true
      },
      ...
   },
   "email_students":true,
   "auto_enroll":true
}

Account validation

Validates the account registration form. Calls the /api/user/v1/validation/registration API endpoint.

Args:

• url: url of the LMS (base or site). If not specified, uses the base url of the session. Defaults to the LMS base.
• **kwargs: dict with form parameters to validate. E.g.:

{
    email=<email>,
    username=<username>,
    name=<name>,
    password=<password>,
    honor_code=<honor_code>,
    terms_of_service=<terms_of_service>,
}

Returns: dict in the form:

{
    'validation_decisions': {
        <field name>: <validation result, or empty if success>,
        ...
    },
    'username_suggestions': [<username suggestions * 3>]
}

Account registration

Registers a new user account. Calls the /api/user/v1/account/registration/ API endpoint.

Args:

• email: email to register
• username: username to register
• name: full name of the user
• password: password

• url: url of the LMS (base or site). If not specified, uses the base url of the session.

  Defaults to the LMS base.

Additional default fields accepted:

• name: full name of the user

• level_of_education *: one of:

  • 'p': 'Doctorate'
  • 'm': "Master's or professional degree"
  • 'b': "Bachelor's degree"
  • 'a': "Associate degree"
  • 'hs': "Secondary/high school"
  • 'jhs': "Junior secondary/junior high/middle school"
  • 'el': "Elementary/primary school"
  • 'none': "No formal education"
  • 'other': "Other education"

• gender *: can be 'm', 'f', or 'o'
• mailing_address *
• city *
• country: ISO3166-1 two letters country codes as used in django_countries.countries *
• goals *
• year_of_birth *: numeric 4-digit year of birth
• honor_code *: Bool. If mandatory and not set will not create the account.
• terms_of_service *: Bool. If unset, will be set equally to honor_code
• marketing_emails_opt_in *: Bool. If set, will add a is_marketable user attribute (see Student > User Attributes in Django admin)
• provider: Oauth2 provider information
• social_auth_provider: Oauth2 provider information

* Can be set as hidden, optional or mandatory in REGISTRATION_EXTRA_FIELDS setting.

Returns: Dict with the form:

• If successful:

{
    'success': True,
    'redirect_url': <redirection url to finish the authorization and go to the dashboard>
}

• If error:

{
    <field name>: [
        {'user_message': <error message>}
    ]
    'error_code': <error code>,
    'username_suggestions': [<username suggestions> * 3]
}

How to Contribute

To contribute, please send a message to [email protected]