Web services: Difference between revisions

Revision as of 21:31, 2 April 2020

How it works

This simple example will give you an idea of how our web services infrastructure works.

The client sends a username and password to the web service login script.
The script returns a token for that user account.
The client calls a particular web service function on a protocol server including the token .
The protocol server uses the token to check that the user can call the function.
The protocol server calls the matching external function, located in a externallib.php file inside the relevant module.
The external function checks that the current user has_capability to do this operation.
The external function calls the matching Moodle core function (in lib.php usually).
The core function can return a result to the external function.
The external function will return a result to the protocol server.
The protocol server returns the result to the client.

Developer documentation

The full API can be found on any Moodle sites under Administration block > Plugins > Web services > API Documentation.

Note: Additional services are available for uploading and downloading files which are not in the API Documentation - they are accessed in a different way. See Web services files handling

@@ Line 1: / Line 1: @@
-#REDIRECT [https://docs.moodle.org/20/en/Web_services]
+=== How it works ===
+This simple example will give you an idea of how our web services infrastructure works.
-{{Moodle_2.0}}
+#The client sends a username and password to the web service login script.
+#The script returns a token for that user account.
-==Introduction==
+#The client calls a particular web service function on a protocol server including the token .
-This page describes the Web Services implementation that was added to Moodle 2.0 and is being extended with every subsequent version.
+#The protocol server uses the token to check that the user can call the function.
+#The protocol server calls the matching external function, located in a externallib.php file inside the relevant module.
-We support multiple web service protocols (REST, SOAP, XML-RPC and AMF). If that's not enough, support for new protocols can be added easily.
-== How it works ==
-This simple example will give you an idea of how our web services infrastructure works.  See [[External services security]] for more details.
-#The client sends a username and password to the web service protocol server script.
-#The protocol server returns a session token for that user account (how this is sent depends on the protocol).
-#The client calls a particular web service function including the session token.
-#The protocol server uses the token to check that the web service session is still active.
-#The protocol server call the matching external function, located in a externallib.php file inside the relevant module.
 #The external function checks that the current user has_capability to do this operation.
 #The external function calls the matching Moodle core function (in lib.php usually).
@@ Line 22: / Line 12: @@
 #The protocol server returns the result to the client.
-==Web description format==
+== Developer documentation==
+The full API can be found on any Moodle sites under ''' Administration block > Plugins > Web services > API Documentation'''.
-All functions that can be called via web services are declared in a db/service.php file and can be defined in an externallib.php file somewhere.  The classes we use to define these functions are explained in the [https://docs.moodle.org/en/Development:Web_services_description External Service description document].
-==Web services functions==
-Every Moodle site can provide you with a page listing all function descriptions, with useful advice for any supported protocol.
-At the moment the only way to get the full Moodle web service documentation is:
-# login as admin
-# enable ws documentation into Admin block > Web service > Manage Protocol
-# create a service and add all Moodle functions to it
-# give create_token capability to a none admin user
-# login as this user
-# access your Security Keys page and click on the documentation.
-An issue has been created to make it a lot easier: MDL-28650
-However, here is a list of the functions available in Moodle 2.1:
-user:
-* create_users()
-* delete_users()
-* update_users()
-* get_users_by_id() - returns a list of full user objects specified by user ids (only useful for site admin accounts)
-* get_course_participants_by_id() - returns a list of full user objects in specific courses (that you can see)
-* get_users_by_courseid() - returns some subset of full user objects from a course (perhaps by group or capability)
-course:
-* get_courses()
-* create_courses()
-group:
-* create_groups()
-* get_groups()
-* get_course_groups()
-* delete_groups()
-* get_groupmembers()
-* add_groupmembers()
-* delete_groupmembers()
-enrol:
-* get_enrolled_users() - get some minimal information about the users enrolled in a course (DEPRECATED)
-* get_users_courses() - get list of course ids that a user is enrolled in (if you are allowed to see that)
-* role_assign()
-* role_unassign()
-enrol/manual:
-* manual_enrol_users()
-webservice:
-* get_siteinfo_parameters()
-message:
+'''Note:''' Additional services are available for uploading and downloading files which are not in the API Documentation - they are accessed in a different way. See [[Web services files handling]]
-* send_instantmessages()
-files:
+* [[How to contribute a web service function to core]]
-* get_files()
+* [[Adding a web service to a plugin| Adding a web service to your plugin]]
-* upload()
+* [[Creating a web service client | Implement a web service client]]
+* [[Web services files handling]]
+* [[Web_services_Roadmap | Web service Listing & Roadmap]]
-==Authentication==
+== Specification and brainstorming ==
-Please have a look to the [[External services security]] page
+* [[External services security | External services security]]
+* [[External services description | External services description]]
-==See also==
+== See also ==
-* The official discussion [http://moodle.org/mod/forum/view.php?id=6971| forum is here]
+* [[Web_service_API_functions|Web service API functions]]
-* The tracker issues are here: MDL-12886 and MDL-17135
+* [[:en:Web_services_FAQ|Web services FAQ]]
-* [[External services security]]
+* [[:en:How_to_create_and_enable_a_web_service|How to create and enable a web service]]
-* [[External services description]]
+* [[:en:Enable mobile web services|How to enable the mobile web service]]
-* [[Creating a web service and a web service function]]
+* [[:en:Web_services|Web services user documentation]]
-* [[Creating a web service client]]
+* [http://www.slideshare.net/juanleyva/mastering-moodle-web-services-development Mastering Moodle Web Services development] - Last session of the Hackfest in the MoodleMoot UK 2016
-* [[Web_Services]]
-[[Category:Web Services]]
+[[Category:Web_Services]]