{"id":19591949,"url":"https://github.com/catalyst/moodle-webservice_restful","last_synced_at":"2025-04-09T23:16:27.621Z","repository":{"id":43557290,"uuid":"127237782","full_name":"catalyst/moodle-webservice_restful","owner":"catalyst","description":"A REStful webservice plugin for Moodle LMS","archived":false,"fork":false,"pushed_at":"2024-11-14T08:44:03.000Z","size":117,"stargazers_count":38,"open_issues_count":19,"forks_count":30,"subscribers_count":16,"default_branch":"MOODLE_402_STABLE","last_synced_at":"2025-04-09T23:16:24.621Z","etag":null,"topics":["api","catalyst","lms","moodle","php"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/catalyst.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-03-29T04:44:19.000Z","updated_at":"2025-01-28T06:10:03.000Z","dependencies_parsed_at":"2024-05-06T05:25:39.649Z","dependency_job_id":"a68de06b-ca31-4fd4-8c79-597108a974d9","html_url":"https://github.com/catalyst/moodle-webservice_restful","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catalyst%2Fmoodle-webservice_restful","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catalyst%2Fmoodle-webservice_restful/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catalyst%2Fmoodle-webservice_restful/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catalyst%2Fmoodle-webservice_restful/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/catalyst","download_url":"https://codeload.github.com/catalyst/moodle-webservice_restful/tar.gz/refs/heads/MOODLE_402_STABLE","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248125593,"owners_count":21051771,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","catalyst","lms","moodle","php"],"created_at":"2024-11-11T08:32:09.322Z","updated_at":"2025-04-09T23:16:27.538Z","avatar_url":"https://github.com/catalyst.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![ci](https://github.com/catalyst/moodle-webservice_restful/actions/workflows/ci.yml/badge.svg?branch=MOODLE_402_STABLE)](https://github.com/catalyst/moodle-webservice_restful/actions/workflows/ci.yml)\n\n# moodle-webservice_restful\nA REStful webservice plugin for Moodle LMS\n\nThis plugin allows Moodle's webservice interface to operate in a more RESTFul way.\u003cbr/\u003e\nInstead of each webservice call having a URL query parameter define what webservice function to use, webservice functions are made available by discrete URLS.\n\nThis makes it easier to integrate Moodle with modern interfaces that expect a RESTful interface from other systems.\n\nThis plugin also supports sending requests to Moodle webservices using the JSON format.\n\nFinally, by default all Moodle webservice requests return the HTTP status code of 200 regardless of the success or failure of the call. This plugin will return 4XX series status codes if calls are malformed, missing data or unauthorised. This allows external services communicating with Moodle to determine the success or failure of a webservice call without the need to parse the body of the response.\n\n## Why make this Plugin?\nThere were two related reasons for making this plugin. The first was to solve a technical problem; interfacing Moodle to a service that required each Moodle webservice to be callable from a unique URL. The second was to advance the maturity of Moodle's webservice interface.\n\nThe \"Richardson Maturity Model\" (https://martinfowler.com/articles/richardsonMaturityModel.html) describes the maturity of a web applications API/ webservice interface in a series of levels.\n\n![Maturity Model](/pix/maturity.png?raw=true)\n\nMoodle is currently Level 0 or in the \"swamp of POX\". As described be Fowler, Moodle \"is using HTTP as a tunneling mechanism for your own remote interaction mechanism\"\n\nThis plugin aims to extend the maturity of Moodle's webservice interface to \"Level 1: Resources\" by making each webservice function available as a discrete URL.\n\n## Supported Moodle Versions\n\n| Moodle version   | Branch            |\n|------------------|-------------------|\n| Moodle 4.2 - 4.4 | MOODLE_402_STABLE |\n| Moodle 3.9 - 4.1 | master            |\n\n## Moodle Plugin Installation\nThe following sections outline how to install the Moodle plugin.\n\n### Command Line Installation\nTo install the plugin in Moodle via the command line: (assumes a Linux based system)\n\n1. Get the code from GitHub or the Moodle Plugin Directory.\n2. Copy or clone code into: `\u003cmoodledir\u003e/webservice/restful`\n3. Run the upgrade: `sudo -u www-data php admin/cli/upgrade` **Note:** the user may be different to www-data on your system.\n\n### User Interface Installation\nTo install the plugin in Moodle via the Moodle User Interface:\n\n1. Log into your Moodle as an Administrator.\n2. Navigate to: *Site administration \u003e Plugins \u003e Install Plugins*\n3. Install plugin from Moodle Plugin directory or via zip upload.\n\n## Moodle Plugin Setup\nOnce the plugin has been installed in Moodle, the following minimal setup is required:\n\n1. Log into your Moodle as an Administrator.\n2. Navigate to: *Site administration \u003e Plugins \u003e Webservices \u003e Manage protocols*\n3. Enable the RESTful protocol by clicking the \"eye icon\" in the enable column for this protocol.\n\n## Moodle Webservice Setup\nFollow these instructions if you do not currently have any webservies enabled and/or unfamiliar with Moodle webservices.\n\nThere are several steps required to setup and enable webservices in Moodle, these are covered in the Moodle documentation that can be found at: https://docs.moodle.org/34/en/Using_web_services\n\nIt is recommended you read through these instructions first before attempting Moodle webservice Setup.\n\n## Accepted Content Types\nData can be sent to Moodle webservices using the following encodings:\n\n* application/json\n* application/xml\n* application/x-www-form-urlencoded\n\nUse the 'Content-Type' HTTP header to notify Moodle which format is being used per request.\n\n## Returned Content Types\nData can be received from Moodle webservices using the following encodings:\n\n* application/json\n* application/xml\n\nUse the 'Accept' HTTP header to notify Moodle which format to return per request.\n\n## Differences to Moodle Standard Webservice Interface\nWhen using the RESTful plugin there are several differences to other Moodle webservice plugins, these are summarised below:\n\n* Webservice function as URL (slash parameter)\n** Instead of being passed as a query parameter webservice functions are passed in the URL, e.g. https://localhost/webservice/restful/server.php/core_course_get_courses this allows each webservice to appear as a unique URL endpoint.\n* Webservice authorisation token as HTTP header\n** Instead of being passed as a query parameter, authorisation tokens are passed using the 'Authorization' HTTP Header.\n* Moodle response format as HTTP header\n** Instead of being passed as a query parameter, the desired Moodle response format ispassed using the 'Accept' HTTP Header.\n\n## Sample Webservice Calls\nBelow are several examples of how to structure requests using the cURL command line tool.\n\n### JSON Request\nThe following example uses the core_course_get_courses webservice function to get the course with id 6. The request sent to Moodle and the response received back are both in JSON format.\n\nTo use the below example against an actual Moodle instance:\n* Replace the {token} variable (including braces) with a valid Moodle authorisation token.\n* Relace localhost in the URL in the example with the domain of the Moodle instance you want to use.\n\n\u003cpre\u003e\u003ccode\u003e\ncurl -X POST \\\n-H \"Content-Type: application/json\" \\\n-H \"Accept: application/json\" \\\n-H 'Authorization: {token}' \\\n-d'{\"options\": {\"ids\":[6]}}' \\\n\"https://localhost/webservice/restful/server.php/core_course_get_courses\"\n\u003c/code\u003e\u003c/pre\u003e\n\n### XML Request\nThe following example uses the core_course_get_courses webservice function to get the course with id 6. The request sent to Moodle and the response received back are both in XML format.\n\nTo use the below example against an actual Moodle instance:\n* Replace the {token} variable (including braces) with a valid Moodle authorisation token.\n* Relace localhost in the URL in the example with the domain of the Moodle instance you want to use.\n\n\u003cpre\u003e\u003ccode\u003e\ncurl -X POST \\\n-H \"Content-Type: application/xml\" \\\n-H \"Accept: application/xml\" \\\n-H 'Authorization: {token}' \\\n-d'\n\u0026lt;root\u0026gt;\n   \u0026lt;options\u0026gt;\n      \u0026lt;ids\u0026gt;\n         \u0026lt;element\u0026gt;6\u0026lt;/element\u0026gt;\n      \u0026lt;/ids\u0026gt;\n   \u0026lt;/options\u0026gt;\n\u0026lt;/root\u0026gt;' \\\n\"https://localhost/webservice/restful/server.php/core_course_get_courses\"\n\u003c/code\u003e\u003c/pre\u003e\n\n### REST / Form Request\nThe following example uses the core_course_get_courses webservice function to get the course with id 6. The request sent to Moodle is in REST format and the response received back is in JSON format.\n\nNOTE: This plugin can only accept requests in REST format. Responses must be in JSON or XML format.\n\nTo use the below example against an actual Moodle instance:\n* Replace the {token} variable (including braces) with a valid Moodle authorisation token.\n* Relace localhost in the URL in the example with the domain of the Moodle instance you want to use.\n\n\u003cpre\u003e\u003ccode\u003e\ncurl -X POST \\\n-H \"Content-Type: application/x-www-form-urlencoded\" \\\n-H \"Accept: application/json\" \\\n-H 'Authorization: {token}' \\\n-d'options[ids][0]=6' \\\n\"https://localhost/webservice/restful/server.php/core_course_get_courses\"\n\u003c/code\u003e\u003c/pre\u003e\n\n### Mixed Request and Response\nThis Moodle webservice plug-in allows for requests and responses to be different formats.\n\nThe following example uses the core_course_get_courses webservice function to get the course with id 6. The request sent to Moodle is in JSON format and the response received back is in XML format.\n\nTo use the below example against an actual Moodle instance:\n* Replace the {token} variable (including braces) with a valid Moodle authorisation token.\n* Relace localhost in the URL in the example with the domain of the Moodle instance you want to use.\n\n\u003cpre\u003e\u003ccode\u003e\ncurl -X POST \\\n-H \"Content-Type: application/json\" \\\n-H \"Accept: application/xml\" \\\n-H 'Authorization: {token}' \\\n-d'{\"options\": {\"ids\":[6]}}' \\\n\"https://localhost/webservice/restful/server.php/core_course_get_courses\"\n\u003c/code\u003e\u003c/pre\u003e\n\nThe received response will look like:\n\n\u003cpre\u003e\u003ccode\u003e\n\u0026lt;RESPONSE\u0026gt;\n\u0026lt;MULTIPLE\u0026gt;\n\u0026lt;SINGLE\u0026gt;\n\u0026lt;KEY name=\"id\"\u0026gt;\u0026lt;VALUE\u0026gt;6\u0026lt;/VALUE\u0026gt;\n\u0026lt;/KEY\u0026gt;\n\u0026lt;KEY name=\"shortname\"\u0026gt;\u0026lt;VALUE\u0026gt;search test\u0026lt;/VALUE\u0026gt;\n\u0026lt;/KEY\u0026gt;\n\u0026lt;KEY name=\"categoryid\"\u0026gt;\u0026lt;VALUE\u0026gt;1\u0026lt;/VALUE\u0026gt;\n\u0026lt;/KEY\u0026gt;\n\u0026lt;KEY name=\"categorysortorder\"\u0026gt;\u0026lt;VALUE\u0026gt;10003\u0026lt;/VALUE\u0026gt;\n\u0026lt;/KEY\u0026gt;\n...\n\u003c/code\u003e\u003c/pre\u003e\n\n## Error Examples\nThe following cURL example will generate various types of errors. These are useful when testing.\n\n### No Aauthorization Header\nThis request is missing the authorization header.\n\n\u003cpre\u003e\u003ccode\u003e\ncurl -i -X POST \\\n-H \"Content-Type: application/json\" \\\n-H \"Accept: application/json\" \\\n-d'{\"options\": {\"ids\":[6]}}' \\\n\"http://moodle.local/webservice/restful/server.php/core_course_get_courses\"\n\u003c/code\u003e\u003c/pre\u003e\n\n### Invalid Token\nThis request contains an invalid webservice token.\n\n\u003cpre\u003e\u003ccode\u003e\ncurl -i -X POST \\\n-H \"Content-Type: application/json\" \\\n-H \"Accept: application/json\" \\\n-H 'Authorization: xxx' \\\n-d'{\"options\": {\"ids\":[6]}}' \\\n\"http://moodle.local/webservice/restful/server.php/core_course_get_courses\"\n\u003c/code\u003e\u003c/pre\u003e\n\n### No Accept Header\nThis request is missing the Accept header.\n\n\u003cpre\u003e\u003ccode\u003e\ncurl -i -X POST \\\n-H -i \"Content-Type: application/json\" \\\n-H 'Authorization: e71561c88ca7f0f0c94fee66ca07247b' \\\n-d'{\"options\": {\"ids\":[6]}}' \\\n\"http://moodle.local/webservice/restful/server.php/core_course_get_courses\"\n\u003c/code\u003e\u003c/pre\u003e\n\n\n## Roadmap\nThe next big step will be to update the interface to \"Level 2\" that is support HTTP verbs, like get and post.\u003cbr/\u003e\nWhich verb to use will likely be dependant on the ws function name that is being invoked.\n\nIf you have any suggestions for functionality, they can be requests by raising a GitHub issue: https://github.com/catalyst/moodle-webservice_restful/issues\n\n# Crafted by Catalyst IT\n\nThis plugin was developed by Catalyst IT Australia:\n\nhttps://www.catalyst-au.net/\n\n![Catalyst IT](/pix/catalyst-logo.png?raw=true)\n\n\n# Contributing and Support\n\nIssues, and pull requests using github are welcome and encouraged! \n\nhttps://github.com/catalyst/moodle-webservice_restful/issues\n\nIf you would like commercial support or would like to sponsor additional improvements\nto this plugin please contact us:\n\nhttps://www.catalyst-au.net/contact-us\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcatalyst%2Fmoodle-webservice_restful","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcatalyst%2Fmoodle-webservice_restful","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcatalyst%2Fmoodle-webservice_restful/lists"}