|
|
| (35 intermediate revisions by 4 users not shown) |
| Line 1: |
Line 1: |
| 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.
| | {{Template:Work in progress}}{{Moodle_2.0}} |
|
| |
|
| Please add new functions if there's functionality you want that isn't covered (we can refactor/whittle at the end).
| | =Introduction= |
| | This page described the Web Services module implemented for Moodle 2.0<br> |
| | The tracker issue is here: MDL-12886<br> |
| | This module is been implemented by the [http://blogs.dfwikilabs.org/moodle_ws/ DFWS Team]. |
|
| |
|
| The tracker bug for all this is here: MDL-12886
| | =Implementation= |
| | Web Services module has been conceived in a purpose to be ported on different Moodle version, and also on different project. It has also for purpose to support multiple web service protocols (REST, SOAP, AMFPHP, ...). Adding a new protocol support should be relatively easy. |
|
| |
|
| ==add user== | | == How does it work == |
| [Feedback]
| | The web service client call a Moodle web service. The web service is located in a folder specific to the used protocol. It's usually a inout.php file. This file runs the web service server and gets the sent parameters. Then it calls a wrapper. The wrapper.php file is implemented in order to call the Moodle API which contains all callable functions. The wrapper will check a "generated file" in order to know which functions are available, and what their parameters and what they returned.<br> |
| Speaking as someone who will be using this API to integrate with another line of business application I would recommend the following changes.
| | For any protocol there should be at least one inout.php file and one wrapper file. |
|
| |
|
| The add_user method should really be a 'SetUser' ie it will create the record if it does not exist or update it it if it does. The ID that is passed into the method would be *our* primary key which Moodle would use to recognise the user record within Moodle. We would not normally need to know anything about the Moodle primary key.
| |
|
| |
|
| One option to make the web services maintainable is to accept XML as a parameter and not a structure or custom object. That way you can define an XSD which will define required\optional parameters. Equally if you include a version number you can change the XML to add new features without having to redefine the web service signature itself (and hence clients will not have to recompile their code). So you may receive a SetUser call with XML V1.0 and another with XML V2.0 on the same webservice but from two different clients supporting different versions of the API.
| | == Technical specs == |
| | # The client calls the web service |
| | # The web service server receives the call |
| | # The web service server transforms the web service params into a common param format to all web service protocol => Format to be defined |
| | # The web service server calls a function call_moodle_function($functionname, $params) |
| | # call_moodle_function() checks through a WS API descriptor class that the params are legal for this function name |
| | # call_moodle_function() call the correct API moodle function |
| | # the call_moodle_function() return the result to the web service server |
| | # the web service server convert the result into a response |
|
| |
|
| The method *must* accept an array of users - it's a little trickier to set this up in the client code but is much more scalable (if there's some good sample code then this is easier anyway). The latency (round trip time) with web service calls is high so you want to do as much as you can in a single call. We have a customer who wants us to deploy Moodle to 40,000 users - we're not going to do that using individual calls.
| | Params should include: |
| [/Feedback]
| | * function parameter names, values and types |
| | * returned object fields (e.g. we cannot return a password field through a get_users function) |
| | * return value and type |
|
| |
|
| 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 ?).
| | =Security= |
| Also password should be "required" if authentication method is "internal" .
| | How are the web services secured ?<br> |
| | Security layer implemented by every protocol? |
|
| |
|
| INPUT:
| | =List of functions= |
| firstname
| | All callable functions are declared into Moodle API, please read [https://docs.moodle.org/en/index.php?title=Development:Moodle_API Moodle API documentation]. |
| lastname
| |
| email
| |
| idnumber
| |
| login
| |
| authentication method (optional , default= manual ?)
| |
| | |
| | |
| | |
| OPERATION:
| |
| Adds a new user to the user database
| |
| | |
| OUTPUT:
| |
| id or false
| |
| | |
| ==delete user==
| |
| INPUT:
| |
| idnumber or
| |
| email or
| |
| id or
| |
| login
| |
| | |
| OPERATION:
| |
| User is marked as deleted
| |
| All it's role assignments are destroyed
| |
| OUTPUT:
| |
| true/false
| |
| | |
| ==get user==
| |
| INPUT:
| |
| 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 course==
| |
| INPUT:
| |
| name
| |
| shortname
| |
| format (default topics)
| |
| idnumber
| |
| | |
| OPERATION:
| |
| Adds a new course to the course table
| |
| | |
| OUTPUT:
| |
| id or false
| |
| | |
| | |
| ==delete course==
| |
| INPUT:
| |
| name OR
| |
| shortname OR
| |
| idnumber OR
| |
| id
| |
| | |
| OPERATION:
| |
| Deletes a course from the course table
| |
| What about associated ressources, roles ...
| |
| | |
| OUTPUT:
| |
| true or false
| |
| | |
| | |
| ==get course==
| |
| INPUT:
| |
| 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 record
| |
| | |
| ==enrol student to course==
| |
| [Feedback]
| |
| It's not clear what the difference is or significance of ID vs. idnumber is. Remember the web service developers will probably not be users of Moodle so it needs to be clear.
| |
| [/Feedback]
| |
| | |
| INPUT:
| |
| course unique Id (Moodle's ID or idnumber or shortname)
| |
| student unique id (Moodle's ID or idnumber or login or email)
| |
| | |
| OPERATION:
| |
| Assign student role to course
| |
| | |
| OUTPUT:
| |
| true or false
| |
| | |
| ==unenrol student from course==
| |
| INPUT:
| |
| course unique Id (Moodle's ID or idnumber or shortname)
| |
| student unique id (Moodle's ID or idnumber or login or email)
| |
| | |
| OPERATION:
| |
| remove student role from course
| |
| | |
| OUTPUT:
| |
| true or false
| |
| | |
| | |
| ==assign role to course==
| |
| INPUT:
| |
| course unique Id (Moodle's ID or idnumber or shortname)
| |
| user unique id (Moodle's ID or idnumber or login or email)
| |
| role id (teacher, non editing teacher, student (?) ...)
| |
| | |
| OPERATION:
| |
| assign given user a "standard" role to given course
| |
| | |
| OUTPUT:
| |
| true or false
| |
| | |
| | |
| ==remove role from course==
| |
| INPUT:
| |
| course unique Id (Moodle's ID or idnumber or shortname)
| |
| user unique id (Moodle's ID or idnumber or login or email)
| |
| role id (teacher, non editing teacher, student (?) ...)
| |
| | |
| OPERATION:
| |
| remove given user's "standard" role from given course
| |
| | |
| OUTPUT:
| |
| true or false
| |
| | |
| | |
| ==get my courses==
| |
| | |
| INPUT:
| |
| user unique id (Moodle's ID or idnumber or login or email)
| |
| | |
| OPERATION:
| |
| return a "list" of course's id in which given user move given user has some role assigned
| |
| | |
| 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 last changes in my courses==
| |
| | |
| 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==
| |
| | |
| 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 ?)
| |
| | |
| ==get group members==
| |
| | |
| OPERATION:
| |
| return a "list" of ids for members of a group (within a course or global)
| |
| | |
| | |
| ==enrol to group==
| |
| | |
| OPERATION:
| |
| add a new member to a group
| |
| | |
| | |
| ==unenrol from group==
| |
| | |
| OPERATION:
| |
| remove membership from a group
| |
| | |
| | |
| ==get calendar events ==
| |
| | |
| OPERATION:
| |
| return a "list" of event's identifiers suitable from the "get event" operation
| |
| | |
| ==get calendar event==
| |
| | |
| OPERATION:
| |
| return in an "exportable" format (iCal, vCal ...)an event recorded in Moodle database (site, course, private ...)
| |
| | |
| ==set calendar event==
| |
| | |
| OPERATION:
| |
| add/modify an event in Moodle database (site, course, private ...)
| |
Note: This article is a work in progress. Please use the page comments for any recommendations/suggestions for improvement.
Moodle 2.0
Introduction
This page described the Web Services module implemented for Moodle 2.0
The tracker issue is here: MDL-12886
This module is been implemented by the DFWS Team.
Implementation
Web Services module has been conceived in a purpose to be ported on different Moodle version, and also on different project. It has also for purpose to support multiple web service protocols (REST, SOAP, AMFPHP, ...). Adding a new protocol support should be relatively easy.
How does it work
The web service client call a Moodle web service. The web service is located in a folder specific to the used protocol. It's usually a inout.php file. This file runs the web service server and gets the sent parameters. Then it calls a wrapper. The wrapper.php file is implemented in order to call the Moodle API which contains all callable functions. The wrapper will check a "generated file" in order to know which functions are available, and what their parameters and what they returned.
For any protocol there should be at least one inout.php file and one wrapper file.
Technical specs
- The client calls the web service
- The web service server receives the call
- The web service server transforms the web service params into a common param format to all web service protocol => Format to be defined
- The web service server calls a function call_moodle_function($functionname, $params)
- call_moodle_function() checks through a WS API descriptor class that the params are legal for this function name
- call_moodle_function() call the correct API moodle function
- the call_moodle_function() return the result to the web service server
- the web service server convert the result into a response
Params should include:
- function parameter names, values and types
- returned object fields (e.g. we cannot return a password field through a get_users function)
- return value and type
Security
How are the web services secured ?
Security layer implemented by every protocol?
List of functions
All callable functions are declared into Moodle API, please read Moodle API documentation.
