Examine Moodle modular plugin architectures, folder directories topology, custom capabilities mappings, and parameter validation structures conceptually.
Moodle relies on a strict modular namespace. To build custom web service endpoints, we place our code within a local plugin directory. Let's trace how the directories are organized and explain why each file is critical.
| File Target | What it Means | Why it is Important |
|---|---|---|
| version.php | Declares plugin component name, release versions, and platform dependencies. | Moodle reads this to execute database schema updates. Skipping this prevents the server from recognizing new functions. |
| db/services.php | Registers your function array, parameter verification class, and security layers. | This registers endpoints inside mdl_external_functions, binding capabilities and ajax configurations. |
| classes/external/progress.php | Contains the actual processing logic, returning structural parameters. | Declares parameter and output schemas using Moodle's built-in validation methods. |
| db/access.php | Defines custom platform permissions or capabilities (like local/courseprogress:view). |
Allows lock-step user role access checks during API requests, preventing unauthorized data views. |
| lang/en/local_courseprogress.php | Declares user-facing text strings for local translations. | Moodle strictly checks for translation files. Missing translation logs will produce severe warning exceptions. |
Moodle validates all inputs and outputs through the external_api framework. This enforces security and structural integrity before logic executions begin:
Moodle web services restrict incoming variables to safe data classes to prevent SQL injections and path traversal exploits:
PARAM_INT: Strict numeric values (such as userid or courseid).PARAM_ALPHA: Standard alphabetical strings only (such as status or action).PARAM_TEXT: Raw user-facing description logs.
Access keys defined under db/access.php (such as local/courseprogress:view) verify if the request owner holds permission inside the target context_course::instance($courseid). This ensures students cannot query administrative logs.
API deployment is a continuous iteration cycle. Understanding the distinction between registering a new endpoint and modifying a class is vital to maintaining uptime:
Requires declaring the configuration block inside db/services.php, bumping the decimal version value inside version.php, and running the Moodle database upgrade controller via CLI. Without a version bump, Moodle ignores configuration additions.
If you are only updating code logic inside classes/external/progress.php (and the endpoint structure remains identical), database upgrade commands are bypassed. However, you must execute a cache purge command to refresh PHP reflection variables cached in system memory.
Looking for the complete, copy-paste codebase files and specification logs for all 13 custom APIs?
Go to Web Service PlaygroundAlways prefix functions with your component name to avoid class conflicts (e.g. local_courseprogress_).
Require minimal necessary permissions. Limit admin functions to system scope contexts.