Moodle Web Service API client with intellisense and typechecking
npm install @webhare/moodle-webservicebash
npm install @webhare/moodle-webservice
`
Get site info (using Promised callbacks)
`ts
import { MoodleApi } from "@webhare/moodle-webservice";
const moodle = MoodleApi({
baseUrl: "https://moodle.example.com", //<-- Put your Moodle URL here
token: "exppsBdQwLvNwYRoAuaiBO5j0aWTzxU6", //<-- Put your token here
});
moodle.core.webservice //<-- with intellisense and type checking
.getSiteInfo()
.then((res) => console.log(res)) //<-- Response of type IMoodleSiteInfo
.catch((err) => console.error(err.message));
`
Get course contents (using async-await approach)
`ts
import { MoodleApi } from '@webhare/moodle-webservice';
const moodle = MoodleApi({ ... });
async function main() {
try {
const sections =
await moodle.core.course.getContents({courseid: 1234});//<-- returns IMoodleCourseSection[]
//Response data
console.log(sections[0].name);
/*
Introduction
*/
}
catch (err) {
console.log(err);
}
}
main();
`
if a token param is provided, it will override the token supplied when instantiating the api
`ts
import { MoodleApi } from "@webhare/moodle-webservice";
const moodle = MoodleApi({
baseUrl: "https://moodle.example.com",
token: "exppsBdQwLvNwYRoAuaiBO5j0aWTzxU6",
});
moodle.core.webservice
.getSiteInfo({ token: "37512512c24112b1235cc123f821bd27cd" }) //<-- This token will be used instead
.then((res) => console.log(res))
.catch((err) => console.error(err.message));
moodle.config.token = "37512512c24112b1235cc123f821bd27cd"; //<-- You can also do this.
//..many function calls with the same token above.
`
Intellisense + Typechecking
Getting your api token.
if you don't immediately have your token to pass to the api you can import MoodleClient directly
and use the authenticate method to get one.
`ts
import { MoodleApi, MoodleClient } from "@webhare/moodle-webservice";
const YOUR_WEBSITE_URL = "https://moodle.example.com";
//No token provided beforehand
const moodle = MoodleApi({
baseUrl: YOUR_WEBSITE_URL, //<-- Put your Moodle URL here
});
async function main() {
try {
//result type of IMoodleWSAuthResponse
const { token } = await MoodleClient.authenticate({
baseUrl: YOUR_WEBSITE_URL,
credentials: { username: "AwesomeJohn", password: "SmartPa33word" },
});
moodle.config.token = token;
const { fullname: firstName } = await moodle.core.webservice.getSiteInfo();
/*
logs:
John Smith
*/
} catch (err) {
console.log(err);
}
}
main();
`
Helper classes
The moodle webservice has some caveats here and there such as how when getting an attempt
moodle doesn't send you all the raw question data, instead some is raw data while other is
the rendered HTML question element.
moodle-webservice aims to solve that by providing a number of helper classes such as MoodleAttempt , these are abstract classes that have a number of functions that aim to solve
these issues.
`ts
import { MoodleApi, MoodleAttempt } from "@webhare/moodle-webservice";
const moodle = MoodleApi({
baseUrl: "https://moodle.example.com",
token: "375208h132h1222h20h202b823b227cd",
});
moodle.mod.quiz.getAttemptReview({ attemptid: 3665103 }).then((res) => {
const questions = res.questions; //<-- of type IMoodleQuestion[].
//IMoodleQuestion does not contain the actual question text or choices.
questions[0].text; //<-- Error no such property on questions
const parsedReview = MoodleAttempt.parse(res);
const parsedQuestions = parsedReview.questions; //<-- of type IMoodleParsedQuestion[].
//IMoodleParsedQuestion contains additional data such as the name, instance number, and choices
console.log(parsedQuestions[0].text);
//Output: "The muscles of facial expression are supplied by the ____ nerve."
});
`
or parse a single question
`ts
import { MoodleApi, MoodleQuestion } from "@webhare/moodle-webservice";
const moodle = MoodleApi({
baseUrl: "https://moodle.example.com",
token: "375208h132h1222h20h202b823b227cd",
});
moodle.mod.quiz.getAttemptReview({ attemptid: 3665103 }).then((res) => {
const questions = res.questions; //<-- of type IMoodleQuestion[].
//IMoodleQuestion does not contain the actual question text or choices.
questions[0].text; //<-- Error no such property on questions
//IMoodleParsedQuestion contains additional data such as the name, instance number and choices
const parsedQuestion = MoodleQuestion.parse(questions[0]); //<-- of type IMoodleParsedQuestion.
console.log(parsedQuestion.text);
//Output: "The muscles of facial expression are supplied by the ____ nerve."
});
`
JSON to form data
Moodle has a peculiar way of specifying request parameters.
Parameters can either be sent in URL query string or POST form body.
Thus a JSON object needs to be converted to form data
`json
{
"users": [
{
"firstname": "Foo",
"lastname": "Bar",
"username": "foo",
"password": "FooBar123!",
"email": "foo@example.com"
}
]
}
`
As Content-Type: application/x-www-form-urlencoded
`
users[0][firstname]=Foo&users[0][lastname]=Bar&users[0][username]=foo&users[0][password]=FooBar123%21&users[0][email]=foo%40email.com
`
To perform the conversion in the code invoke the flatten function
`ts
import { MoodleClient } from "@webhare/moodle-webservice";
const form = MoodleClient.flatten({
users: [
{
firstname: "Foo",
lastname: "Bar",
username: "foo",
password: "FooBar123!",
email: "foo@example.com",
},
],
});
console.log(form); //users[0][firstname]=Foo&users[0][lastname]=Bar...
`
However, there is no need to invoke the function outside the code as anything passed as data parameter to api functions is automatically flattened and formatted in the right way.
List of functions
Offical list of functions can be found at Web service API functions
The following table represents mapping between JavaScript function names and Moodle Web Service function names.
| JS function | API function | Description |
| ----------------------------------------------------------------------------------- | ------------------------------ | -------------------------------------------------------------- |
| auth.email.getSignupSettings(data) | auth_email_get_signup_settings | Get the signup required settings and profile fields. |
| auth.email.signupUser(data) | auth_email_signup_user | Adds a new user (pendingto be confirmed) in the site. |
| core.user.createUsers(data) | core_user_create_users | Create users - admin function |
| core.webservice.getSiteInfo(data) | core_webservice_get_site_info | Return some site info / user info / list web service functions |
| Read more... | | |
Note that the data argument is not always required and can be omitted.
Note regarding types
Due to poor moodle webservice function documentation not all functions have definite parameter types
and instead have IMoodleWSParams as its parameter type and any as its return type.
I've added types for the most important functions first, and I'll keep adding more as I go,
contact me if you want to add types for a function that you know about.
Running your own moodle
For development/testing against a Moodle consider using the docker containers defined in my-moodle:
`bash
cd my-moodle/
docker-compose up
now: open http://127.0.0.1:8051/
`
See https://hub.docker.com/r/bitnami/moodle for details about these containers
After starting, login at http://127.0.0.1:8051/ using: user/bitnami
$3
- http://127.0.0.1:8051/admin/settings.php?section=optionalsubsystems
- Enable webservices
- http://127.0.0.1:8051/admin/settings.php?section=webserviceprotocols
- Enable REST
- Enable documentation
- http://127.0.0.1:8051/admin/settings.php?section=webservicesoverview helps you enroll the service - shows the steps and links
- http://127.0.0.1:8051/admin/settings.php?section=externalservices
- Add service. Configure as needed, don't forget to enable the functions you need
- This is also where you need to go back to add more functions later
- http://127.0.0.1:8051/admin/webservice/tokens.php?action=create
- Get the token. You'll need it for MODULE_TOKEN below
To test the module:
``bash