webservice/upgrade.txt

   1 This files describes API changes in /webservice/*
   2 information provided here is intended especially for developers.
   3
   4 This information is intended for authors of webservices, not people writing webservice clients.
   5
   6 === 4.2 ===
   7
   8 * External function core_webservice_external::get_site_info() does not throw exceptions for missing components anymore.
   9
  10 === 4.1 ===
  11
  12 * The XMLRPC webservice (protocol) has been completely removed. It's now available in the plugins directory.
  13
  14 === 4.0 ===
  15
  16 * User access related exceptions have been changed to use the moodle_exception class instead of the
  17   generic webservice_access_exception, the main reason for this change is to allow clients to
  18   implement some code logic against an access error.
  19
  20 === 3.11 ===
  21
  22 * The method webservice::get_user_capabilities() is deprecated now without a replacement. It has been used
  23   internally only to populate the list of missing capabilities. That functionality has been improved so that
  24   it no longer needs this standalone method.
  25
  26 === 3.10 ===
  27
  28 * The class externallib_advanced_testcase, used in unit tests, has a new function called "configure_filters" to easily configure filters for external functions testing.
  29
  30 === 3.8 ===
  31
  32 * Ajax calls can now specify a cache key. This allows for better caching capabilities on servers. If a cache key
  33   is passed and the web service call does not require the user to be logged in we will attempt to use GET for the
  34   request. This allows for things like proxy caching on URLs. The cache key must be changed if we do not want to
  35   retrieve what has been cached and want to perform the request again.
  36 * External function core_webservice_external::get_site_info() now returns the user private access key "userprivateaccesskey".
  37   This key could be used for fetching files via the tokenpluginfile.php script instead webservice/pluginfile.php to avoid
  38   multiple GET requests that include the WS token as a visible parameter.
  39 * External function core_webservice_external::get_site_info() now returns a new field "userissiteadmin" indicating if
  40   the current user is a site administrator.
  41
  42 === 3.7 ===
  43
  44 * External function core_webservice_external::get_site_info() now returns the current site theme (for the user).
  45
  46 === 3.4 ===
  47
  48 * External function core_webservice_external::get_site_info() now returns the calendar type used in the site and
  49   by the user in the sitecalendartype and usercalendartype fields.
  50 * Implementations of forms for test clients now must follow naming schema: WSFUNCTIONNAME_testclient_form
  51   The old naming schema WSFUNCTIONNAME_form caused conflicts with existing classes.
  52   New class webservice_test_client_base_form can be used as a base class for such forms.
  53
  54 === 3.2 ===
  55
  56 * webservice->get_external_functions now returns the external function list ordered by name ASC.
  57 * The filearea optional parameter has been removed from webservice/upload.php.
  58   Since Moodle 3.1 all the uploads go to the draft area.
  59 * external_format_text() function: component, filearea and itemid are now optional parameters.
  60   In some contexts those parameteres are not necessary because is not required to do a file rewrite via
  61   file_rewrite_pluginfile_urls.
  62 * External function get_site_info now returns the site course ID. This new field is marked as VALUE_OPTIONAL for backwards compatibility.
  63 * A new field "privatetoken" has been added to the "external_tokens" table.
  64   This private token must be safely stored (or not stored at all) by the client because it will be used in places where a request
  65   must be double-checked.
  66   This token should not be passed via GET paramaters and it must be transmitted only via https.
  67   This token is generated only in login/token.php after the user credential has been confirmed. It can't be generated by admins.
  68
  69 === 3.1 ===
  70
  71 * The xmlrpc backend has changed, Zend_XmlRpc has been dropped and there might be slight differences in
  72   responses. Fault strings that were generated by Zend_XmlRpc_XXX_Exception exceptions (i.e. 'Method
  73   "[methodname]" does not exist') are no longer used which may display a different error message depending
  74   on the string returned by the getMessage() method of the thrown exception.
  75 * The xmlrpc server is no longer enabled when the Mobile service is activated.
  76 * Support for the AMF protocol has been dropped completely.
  77 * As Zend Framework has been removed, the webservice_zend_* classes have also been removed.
  78 * Zend_SOAP has been dropped. The native PHP SoapClient and SoapServer classes are now being used instead. WSDL is now
  79   generated by the new class webservice_soap_wsdl. For fault strings, a different error message might be shown depending
  80   on the string returned by the getMessage() method of the thrown exception.
  81 * With Zend_SOAP dropped, moodle_zend_soap_server is now also deprecated.
  82 * As mentioned in the 2.9 notes, deprecated web service functions have now been removed.
  83 * Since our new XML-RPC server implementation does not support introspection, it is critical that all clients send
  84   parameters in the correct order.
  85 * File uploading to the user private file area via the webservice/upload.php script is not supported anymore.
  86   Only uploads to the draft area are allowed.
  87
  88 === 3.0 ===
  89
  90 * WS protocols webservice/myprotocol:use capabilities were defined with a high riskbitmask value
  91   when the fact that a user has that capability does not imply any risk, but other capabilities
  92   that the user may have do. If your ws protocol does not imply and risk by itself, you can remove the
  93   riskbitmask from your $capabilities array in webservice/myprotocol/db/access.php
  94 * New function for formatting external strings: external_format_strings, it should be used as a replacement of format_string in
  95   external functions.
  96   All the occurrences of format_strings have been replaced with this new function.
  97
  98 === 2.9 ===
  99
 100 * The deprecated functions can not be added to services anymore and
 101   a debugging message for developers is triggered when viewing an existing
 102   services using them. It is recommended to replace calls to the deprecated
 103   functions for calls to the proposed replacements. If you are using a moodle
 104   mobile app fork, it is recommended to update your customisations on top of
 105   the latest moodle mobile app version.
 106
 107   The web services functions that will be finally deprecated in the next
 108   moodle version are:
 109     - moodle_course_create_courses
 110     - moodle_course_get_courses
 111     - moodle_enrol_get_enrolled_users
 112     - moodle_enrol_get_users_courses
 113     - moodle_enrol_manual_enrol_users
 114     - moodle_file_get_files
 115     - moodle_file_upload
 116     - moodle_group_add_groupmembers
 117     - moodle_group_create_groups
 118     - moodle_group_delete_groupmembers
 119     - moodle_group_delete_groups
 120     - moodle_group_get_course_groups
 121     - moodle_group_get_groupmembers
 122     - moodle_group_get_groups
 123     - moodle_message_send_instantmessages
 124     - moodle_notes_create_notes
 125     - moodle_role_assign
 126     - moodle_role_unassign
 127     - moodle_user_create_users
 128     - moodle_user_delete_users
 129     - moodle_user_get_course_participants_by_id
 130     - moodle_user_get_users_by_courseid
 131     - moodle_user_get_users_by_id
 132     - moodle_user_update_users
 133     - core_grade_get_definitions
 134     - core_user_get_users_by_id
 135     - moodle_webservice_get_siteinfo
 136
 137 * External function core_webservice_external::get_site_info now returns additional optional fields:
 138    - advancedfeatures: Array listing Moodle advanced features and if enabled or not.
 139    - usercanmanageownfiles: Whether the my files option is disabled.
 140    - userquota: User storage quota.
 141    - usermaxuploadfilesize: Files upload size limit.
 142
 143
 144 === 2.7 ===
 145
 146 * All webservice server.php and simpleserver.php scripts must define('WS_SERVER', true)
 147   before including config.php file.
 148
 149
 150 === 2.6 ===
 151
 152 * webservice/upload.php
 153 Accepts 2 new post parameters to allow uploading of files to a users draft area.
 154  - filearea should be either 'private' (default) or 'draft'
 155  - itemid unused if the filearea is 'private', for 'draft' it can be the id of a previously
 156    created draft area - or 0 which will generate a new draft area for the files.
 157