It cannot be fixed properly to return manual grade items and category items, because the return signature has hardcoded "activityid" and not "gradeitemid" and already existing hacks to insert the word "course" in the activityid response.
A proper useful function to retrieve student grades would be great - it would need https://tracker.moodle.org/browse/MDL-50582 to land first.
Do we have a good deprecation process for web service functions?
If this was a Moodle internal API, we would
- Implement the new function / class / whatever API change.
- Modify the old functions so that using them causes a warning message.
- Announce in the release notes for that Moodle release that the old API is now deprecated.
- A few Moodle releases later, remove the old API.
- Announce in the release notes for that Moodle release that the old API is now gone.
That is a good system. Can we come up with an equivalent for web service APIs?
The only place I can think of to put the warning message is in the PHP logs on the Moodle server, and they are highly likely to not be seen. However, I hope there is a better option that I have failed to think of.
The way this was done previously was just through the description of the method in the db/services.php which is shown in the webservices api documentation pages.
E.g. "DEPRECATED: this deprecated function will be removed in a future version. This function has been renamed as core_webservice_get_site_info()"
Well, it definitely looks like we should deprecate this function, and create a non-bonkers function that does the job right.
+1 to remove that function
As an alternative, I implemented this function: https://github.com/moodle/moodle/blob/MOODLE_29_STABLE/grade/report/user/externallib.php#L64 to retrieve the gradebook for users.
Note that this function rely in the report API, the information returned is not ready to be treated by external SIS but it's useful if you want to build a visual representation of the user gradebook.