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