Exploring Moodle's API

API centric architecture is a coming thing in technology circles. It’s the way vendors and central IT folk will build systems. It is also going to be manna from heaven for institutionalised people who are breaking a little BAD.

Moodle has a growing web services API. The following documents some initial exploration of how and if you can “break BAD” with those APIs.

Background

Web services API

Moodle has a capability for plugins to define a Web services API. The question is, how many plugins provide this and how much of Moodle core has exposed APIs. It’s likely to be quite large given APIs are increasingly used for mobile devices.

A quick check of my basic Moodle 2.9 install reveals
[code lang=”bash”]
dj:moodle david$ find . -name services.php
./admin/mnet/services.php
./enrol/manual/db/services.php
./enrol/self/db/services.php
./lib/db/services.php
./message/output/airnotifier/db/services.php
./mod/assign/db/services.php
./mod/forum/db/services.php
./mod/lti/services.php[/code]

Not a huge number, but at least enough to start playing with (assign and forum are likely to be particularly useful) and there may well be more.

Of course, I should be looking to add a Web services API to BIM. This page will apparently help with that.

That page also includes a template with a test client. Could be useful later on.

What about the Core APIs

Moodle defines a number of Core APIs that are used within Moodle. Are these available via Web services? Some (all?) wouldn’t make sense, but maybe…

External functions API

The external functions API apparently “allows you to create fully parameterised methods that can be accessed by external programs (such as Web services API)”. Searching for evidence of that in my Moodle install is a little more heartening

[code lang=”bash”]
dj:moodle david$ find . -name externallib.php
./calendar/externallib.php
./cohort/externallib.php
./course/externallib.php
./enrol/externallib.php
./enrol/manual/externallib.php
./enrol/self/externallib.php
./files/externallib.php
./grade/externallib.php
./group/externallib.php
./lib/external/externallib.php
./lib/externallib.php
./message/externallib.php
./message/output/airnotifier/externallib.php
./mod/assign/externallib.php
./mod/forum/externallib.php
./notes/externallib.php
./user/externallib.php
./webservice/externallib.php[/code]

Just have to figure out if the presence of these implies connections with a Web services API and the ability to access from a client.

Web Services

Which brings me to the Web Services category page. There’s also a web services forum and a related FAQ, which includes:

• Details of where to see the available API for your Moodle install.
• A pointer to the Web services roadmap which indicates that it’s still a work in progress.
  It does give a list of what has been implemented. Bingo, activity completion data (at least in 2.9) is included.
• Includes details of how to create a new web service with the advice of using a local plugin.
  This might be a possible kludge where Moodle hasn’t yet provided what might be needed.
• A pointer to how to get a user token for a script.

Security

External services security outlines various ways services can be called and how security is handled.

Using web services on my Moodle instance

As per these instructions and elsewhere

1. Enabling web services.
2. Enabling protocols

   Appears REST is enabled by default (don’t think I did this earlier).

Explore – Site administration / Plugins / Web Services – and its range of options

1. Overview.
   Includes directions on steps for enabling web services for mobile devices and for external systems to control Moodle.
2. User.
   Need to allocate permission to use web services to specified users.
3. Add services to be used.
   Which web services can the user use. In this case, a range of “built-in services” were already enabled for “all users” (assuming they have the required capabilities). This might be interesting to test and explore. Includes a broad array of interesting functionality (mod_assign_get_???) but not overly long.

   Adding a service requires specification of the functions to be enabled.

4. Each service can be configured to a particular user or multiple users.
5. Create a token – select a user and the service.
6. And then there’s a test client embedded in Moodle.
   Which only allows testing of a small subset. Looks like having to write a client will be required.
   Tried a function via the test API. Got a security error. Added it to the functions in the service I’d set up, and hey presto it worked.

Writing a client

There’s a github repo with sample-ws-clients. I’ll use the <a href="https://github.com/moodlehq/sample-ws-clients/tree/master/PHP-REST"PHP-REST code.

1. Clone the repository
2. Modify the token, URL, etc.
3. Use the API documentation to figure out the correct format for the request.
   Which was quite straight forward
   [code lang=”php”]
   $functionname = ‘moodle_user_get_users_by_id’;
   $restformat = ‘xml’;
   $userids = array( 489, 2 );
   $params = array(‘userids’ => $userids);
   [/code]
4. Change the format to json and it works just as well, but of course different format in the data returned.

The JSON option (from 2.2 onwards) means that planned use within the browser should work fine.

Exploring functions of interest

In the short term, I’m particular interested in whether there are existing functions for the following tasks

• Get all enrolled users (and perhaps just students) in a course.
  course_enrol_get_enrolled_users( $course_id )
  Also accepts:
  [code lang=”php”]
  options => array(
  withcapability => string,
  groupid => int,
  onlyactive => int,
  userfields => Array( string, string..),
  limitfrom => int,
  limitnumber => int )
  [/code]
• Get a user’s activity completion details.
  Appears to be implemented in 2.9. Will update my version and see if it appears. Yes.
  core_completion_get_course_completion_status( int courseid )
  Returns a list of statuses including: comment id (cmid), activity module name (modname), instance ID (instance), state (0 incomplete, 1 complete, 2 complete pass, 3 complete fail), timecompleted, tracking (0 none, 1 manual, 2 automatic) )
• Get information about status and results of assignments.
  • mod_assign_get_assignments( array of course ids )
    Returns a list of courses, but also a list of assignment details.
  • mod_assign_get_grades( array of assignment ids )
    Returns a list of assignments and a list of grades for each assignment. Grades include the userid, attemptnumber, timecreated, timemodified, grader and grade.
  • mod_assign_get_submissions( array of assignment ids )
    Similar to get grades but includes status, also submission plugin, list of files and additional information
  • mod_assign_get_user_flags( array of assignment ids )
    Flags include workflowstate, allocated marker, and extension date.

Some longer term services

Longer term some other areas of interest might include

• Adding web services to BIM.

  A job for me at a later date.

• core_message – list of services around the messaging services, perhaps as a way to intervene?