Note: You are currently viewing documentation for Moodle 3.6. Up-to-date documentation for the latest stable version of Moodle is likely available here: Web services.

Development:Web services: Difference between revisions

From MoodleDocs
No edit summary
 
(90 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{Template:Work in progress}}
{{Moodle_2.0}}


=Introduction=
==Introduction==
This page described the Web Services module implemented for Moodle 2.0
This page described the Web Services module implemented for Moodle 2.0<br>
The official discussion [http://moodle.org/mod/forum/view.php?id=6971| forum is here]<br>
The tracker issues are here: MDL-12886 and MDL-17135<br>
This module is been implemented by Moodle HQ and [http://blogs.dfwikilabs.org/moodle_ws/ DFWS Team].


=How does it works=
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.
Web Services module has been conceive in a purpose to be ported on different Moodle version, and also on different project. It has also for purpose to support multiple web services protocol, adding a new protocol should be relatively easy.


=List of functions=
== How it works ==
All callable functions are declared into Moodle API, please read [https://docs.moodle.org/en/index.php?title=Development:Moodle_API Moodle API documentation].
This following example would work but it will not be the unique way to access web services. Please have a look to the [[Development: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.
#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.


This page is to decide on a STANDARD list of CORE web service functions that we should support in Moodle (by XMLRPC, REST and SOAP with the option to plug in AMFPHP for Flash/Flex interfaces) as an API for those writing code to work against Moodle.
==Web description format==


The tracker bug for all this is here: MDL-12886
All functions that can be called via web services can be declared in a db/service.php file and can be defined in an externallib.php file somewhere. The description of the functions that can be called, and what parameters they require, are explained in the [https://docs.moodle.org/en/Development:Web_services_description External Service description document].


=FOLLOWING DOCUMENTATION WILL NEED TO BE DELETED=
==Web services technical documentation==
==add_users==
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
I think we should require all data needed for a successful "first login" to Moodle without popping him out the profile page to fill in all missing required data. This may require extra inputs such as city, description ... (unsure of the full list depending of Moodle version ?).
''
Also password should be "required" if authentication method is "internal" .


INPUT:
==Authentication==
one or more of these in an array
Please have a look to the [[Development:External services security]] page
    firstname
==See also==
    lastname
* [[Development:External services security]]
    email
* [[Development:External services description]]
    idnumber
* [[Development:Creating_a_web_service_and_a_web_service_function]]
    login
* [[Development:Creating a web service client]]
    authentication method (optional , default= manual ?)
* [[Web_Services]]


 
[[Category:Web Services]]
 
OPERATION:
    Adds one or more new users to the user database
 
OUTPUT:
    array of ids or false
 
==delete_users==
INPUT:
    String: field name ('id' or 'idnumber' or 'email' or 'login')
    Array: values
 
OPERATION:
    User is marked as deleted
    All it's role assignments are destroyed
OUTPUT:
    true/false
 
To Be Defined:
*Security: avoid devastating calls such as delete_users ('confirmed',array(1)) or delete_users('firstname',array('patrick')). Where to implement it?
*Wildcards: such as delete_users (array('idnumber','CS%'). Permit or not?
 
==get_users==
INPUT:
one or more of these
    idnumber  or
    email or
    id or
    login
 
OPERATION:
    user record with optional fields set (Moodle 1.8 and later) and maybe some fields filtered out (password,
    email if user said not to disclose it ...) depending of the identity of the "caller" (admin or the user himself)
 
OUTPUT:
    false  or user record
 
==add_courses==
INPUT:
one or more of these in an array
    name
    shortname
    format (default topics)
    idnumber
 
OPERATION:
    Adds a new course to the course table
 
OUTPUT:
    id or false
 
 
==delete_courses==
INPUT:
one or more of these in an array
    name OR
    shortname  OR
    idnumber OR
    id
 
OPERATION:
    Deletes courses from the course table
    What about associated ressources, roles ...
 
OUTPUT:
    true or false
 
 
==get_courses==
INPUT:
one or more of these in an array
    id or  idnumber or shortname
 
OPERATION:
    fetch course record with some fields filtered out depending of the "caller" identity (admin, teacher, student ...)
OUTPUT:
    false  or course records in an array
 
Doubts: so id , idenumber or shortname stands for... user, category, the very course you want to get itself?
 
==add_enrolments==
INPUT:
  course unique Id (Moodle's ID or idnumber or shortname)    (could be one or an array)
  user unique id (Moodle's ID or idnumber or login or email)  (could be one or an array)
  role id (id or shortname or legacy capability name)  (could be one or an array)
 
OPERATION:
  assign given user a given role to given course 
 
OUTPUT:
    true or false
 
 
==delete_enrolments==
INPUT:
  course unique Id (Moodle's ID or idnumber or shortname)    (could be one or an array)
  user unique id (Moodle's ID or idnumber or login or email)  (could be one or an array)
  role id (teacher, non editing teacher, student (?) ...)    (could be one or an array)
 
OPERATION:
  remove given user's "standard" role from given course 
 
OUTPUT:
    true or false
 
 
==get_enrolments==
 
INPUT:
  user unique id (Moodle's ID or idnumber or login or email)
  context course or site
 
OPERATION:
  return a "list" of course's id in which given user move given user has some role assigned   
  return all the roles for a given courseid
 
OUTPUT:
    "array" of (course id, course shortname, course fullname, role id, role name, course url)
    or false in case of error (bad user id)
 
==get_recent_activity==
 
INPUT:
  user unique id (Moodle's ID or idnumber or login or email)
  course unique Id (Moodle's ID ,idnumber or shortname) - optional (default = all my courses)
  timestamp - optional (default = time of last connexion in every course)
 
OPERATION:
  return a "list" of changes (resource added/modified, new activities, etc.) for courses in which given user has some role assigned - since timestamp or last connexion in given course
 
OUTPUT:
    "array" of (course id, course shortname, course fullname, role id, role name, url of the resource/activity, time of change)
    or false in case of error (bad user/course id)
 
 
==get_grades==
 
(see grade_get_course_grade in grade/querylib.php)
 
INPUT:
  user unique id (Moodle's ID or idnumber or login or email)
  course unique Id (Moodle's ID ,idnumber or shortname) - optional (default = all my courses)
 
OPERATION:
  return a "list" of grades and statistics for the given student in the given course
 
OUTPUT:
    "array" of grades records (name,maxgrade,grade,percent,weight,weighted,sortOrder)
    and "array" of stats (gradeItems,allgrades, points,totalpoints, percent, weight, weighted;) 
    or false in case of error (bad user/course id or user not in course)
 
 
==get_groups==
 
OPERATION:
  return a "list" of group records in a given course (or site ?)
 
==add_groups==
 
==delete_groups==
 
==get_group_members==
 
OPERATION:
  return a "list" of ids  for members of a group (within a course or global)
 
==add_group_members==
 
OPERATION:
  add new members to a group
 
==delete_group_members==
 
OPERATION:
  remove membership from a group
 
==add_calendar_events==
 
OPERATION:
  add/modify an event in Moodle database (site, course, private ...)
 
==delete_calendar_events ==
 
OPERATION:
  delete given events
 
==get_calendar_events==
 
OPERATION:
  return in an "exportable" format (iCal, vCal ...)an event recorded in Moodle database (site, course, private ...)

Latest revision as of 09:50, 4 February 2010

Template:Moodle 2.0

Introduction

This page described the Web Services module implemented for Moodle 2.0
The official discussion forum is here
The tracker issues are here: MDL-12886 and MDL-17135
This module is been implemented by Moodle HQ and DFWS Team.

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 would work but it will not be the unique way to access web services. Please have a look to the Development:External services security page for more details.

  1. The client sends a username and password to the web service protocol server script.
  2. The protocol server returns a session token for that user account (how this is sent depends on the protocol).
  3. The client calls a particular web service function including the session token.
  4. The protocol server uses the token to check that the web service session is still active.
  5. The protocol server call the matching external function, located in a externallib.php file inside the relevant module.
  6. The external function checks that the current user has_capability to do this operation.
  7. The external function calls the matching Moodle core function (in lib.php usually).
  8. The core function can return a result to the external function.
  9. The external function will return a result to the protocol server.
  10. The protocol server returns the result to the client.

Web description format

All functions that can be called via web services can be declared in a db/service.php file and can be defined in an externallib.php file somewhere. The description of the functions that can be called, and what parameters they require, are explained in the External Service description document.

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

Authentication

Please have a look to the Development:External services security page

See also

Retrieved from "https://docs.moodle.org/36/en/index.php?title=Development:Web_services&oldid=68174"
Powered by MediaWiki