Web services: Difference between revisions

Revision as of 14:53, 4 April 2016

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 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).
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.

@@ Line 1: / Line 1: @@
-{{Moodle_2.0}}
+=== How it works ===
+This simple example will give you an idea of how our web services infrastructure works.
-=Introduction=
+#The client sends a username and password to the web service login script.
-This page described the Web Services module implemented for Moodle 2.0<br>
+#The script returns a token for that user account.
-The official discussion [http://moodle.org/mod/forum/view.php?id=6971| forum is here]<br>
+#The client calls a particular web service function on a protocol server including the token .
-The tracker issue is here: MDL-12886<br>
+#The protocol server uses the token to check that the user can call the function.
-This module is been implemented by Moodle HQ and [http://blogs.dfwikilabs.org/moodle_ws/ DFWS Team].
-=Implementation=
-The Web Services module has been conceived in order to be ported to different Moodle versions and for different projects. The objective is to support multiple web service protocols (REST, SOAP, XML-RPC and AMF). Adding support for a new protocol should be relatively easy.
-== How it works ==
-This following example works but it will not be the unique way to access web services. Please have a look to the [[External services security]] page 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.
@@ Line 23: / 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 can be declared in an externallib.php file somewhere. The description of the functions that can be called, and what parameters they require, is defined in the [https://docs.moodle.org/en/Development:Web_services_description|Web Service description page].
-==Web services technical documentation==
-In order to facilitate a Moodle web service client implementation, every Moodle sites will provide a page listing all function descriptions. This page also gives some useful advice for any supported protocol. To call this page: ''your_moodle/webservice/wsdoc.php?protocol=soap
-''
-==API - Function list==
-The web service functions are [[Web_services_API_-_Function_List|listed here]]. (obsolete)
-=Authentication=
-==External application==
-Clients needing to use a web service will need a Moodle user account with the ''''moodle/site:usewebservices'''' capability enabled.  After the first login with username and password the session is retained with a token that gets passed with every web service request (until the session expires).
-The Moodle administrator can control access to the site using the ''''Security -> Web services'''' page, which contains settings for:
-* enabling/disabling particular protocols (SOAP, REST, AMF, XMLRPC, ...)
-* configure protocol-specific settings (though we can't think of any such settings)
-* configure system-wide default settings (stored in config table):
-# IP whitelist
-# Anything else?
-* configure per-user settings (stored in user_preferences):
-# IP whitelist
-# Anything else?
-Each protocol will call a webservice authentication function before allowing access, which will:
-# Check that particular protocol is enabled for the system
-# Authenticate the user using username/password and normal auth plugins (internal, LDAP etc)
-# Check that the user has ''''moodle/site:usewebservices'''' at SYSTEM level.
-# Check the per-user restrictions, if there are any, else check the system settings
-# Create a session and return a token for the web service protocol to use.
-This is probably enough (an auth/webservice is not necessary).<br><br><br>
-[[Image:Webserviceadmin.png]]
-<br><br>
-==Embedded application==
-By embedded application, we consider Moodle module or blocks containing a Flash object / other client side code. These new modules or blocks are created by the embedded application creator. <br/>To make it easy to have embedded apps communicate with Moodle, each time the user loads a page with an embedded application, the user should not have to enter his password.
-===Actual Mechanics - step by step of a web service call and authentication for an embedded app===
-# The php page with the embedded app is called.
-# In the php script a function is called to generate a token :
-#* this include an array of functions that the token allows access to. Eg. [0]=>'user/' => 'get_users',[1]=>'forum/' => 'get_forums', [3]=>'mod/{modname}/' => '*',
-#* we restrict the access as much as possible.
-#* Probably for an activity or block for example the token would only allow access to the services for that block.
-# The token is passed into the clientside app through appropriate html - in the case of Flash through Flashvars.
-# When the client calls the web service the token is passed as well as 'credentials'.
-# Moodle recognizes the user from the token. Config.php has a fork in it and sets up the USER and SESSION variables appropriately using the token and not the cookies - tricky.
-===Security===
-In order to minimize security risk :
-* we can make the tokens expire afer a certain period of inactivity of the client app.
-* we can limit the services that the token allows access to. I would suggest that we limit by path of external.php and also to functions within the external.php file.
-===Keeping other data on server side===
-It is usually the case that module id and such is passed to Moodle in the url. In the case of web service calls I think it would be a good idea to store perhaps the contextid on the server side associated with the token. This would increase security.
-So for example for grading an activity we have a web service {activityname}_grade(). Since we have already stored the context id on the server we know the grade is passed is for such and such an activity. We do not pass the contextid as a parameter in the web service call and a web service call cannot be spoofed to pass a grade for another activity once the user has a token.
+* [[How to contribute a web service function to core]]
+* [[Adding a web service to a plugin| Adding a web service to your plugin]]
+* [[Creating a web service client | Implement a web service client]]
+* [[Web services files handling]]
+* [[Web_services_Roadmap | Web service Listing & Roadmap]]
-[[Image:Embedded_app_authentication.png]]
+== Specification and brainstorming ==
+* [[External services security | External services security]]
+* [[External services description | External services description]]
-==See also==
+== See also ==
-* [[External services security]]
+* [[Web_service_API_functions|Web service API functions]]
-* [[External services description]]
+* [[:en:Web_services_FAQ|Web services FAQ]]
+* [[:en:How_to_create_and_enable_a_web_service|How to create and enable a web service]]
+* [[:en:Enable mobile web services|How to enable the mobile web service]]
+* [[:en:Web_services|Web services user documentation]]
+* [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
-[[Category:Web Services]]
+[[Category:Web_Services]]