Talk:Web services - Revision history

Dougiamas: /* Brainstorm for WS Roadmap */

2011-08-12T09:25:21Z

Brainstorm for WS Roadmap

← Older revision		Revision as of 09:25, 12 August 2011
Line 130:		Line 130:
	* get_completed_users_per_course() ?		* get_completed_users_per_course() ?
	* get_completed_courses_per_user() ?		* get_completed_courses_per_user() ?
	* get_users (allows ~~searching~~ by various keys)		* get_users (allows admin to search by various keys)

	course:		course:
Line 140:		Line 140:
	* delete_courses()		* delete_courses()
	* get_course_contents() - including sections, activities etc		* get_course_contents() - including sections, activities etc
			* get_recent_activity() - also works for site course

	group:		group:

Line 184:		Line 185:

	message:		message:

			send_instantmessages()
			* get_instantmessages() - params for unread etc
			* create_contacts()
			* delete_contacts()

			notes:

			create_notes()
			* delete_notes()

			events:

	~~send_instantmessages~~()		* create_event() - triggers an event

			calendar:

			* create_events()
			* update_events()
			* delete_events()

	files:		private files:

	get_files()		get_files()
	upload()		upload() - DEPRECATED
			* create_files() - can also do folders via a flag
			* update_files()
			* delete_files()


	categories:		categories:

Dougiamas: /* Brainstorm for WS Roadmap */

2011-08-12T09:10:28Z

Brainstorm for WS Roadmap

@@ Line 128: / Line 128: @@
      get_users_by_courseid() - returns some subset of full user objects from a course (perhaps by group or capability)
 course:
@@ Line 133: / Line 137: @@
      create_courses()
 group:
@@ Line 142: / Line 150: @@
      add_groupmembers()
      delete_groupmembers()
 enrol:
@@ Line 147: / Line 160: @@
      get_enrolled_users() - get some minimal information about the users enrolled in a course (DEPRECATED)
      get_users_courses() - get list of course ids that a user is enrolled in (if you are allowed to see that)
-    role_assign()
 enrol/manual:
      manual_enrol_users()
 webservice:
@@ Line 166: / Line 191: @@
      get_files()
      upload()

Dougiamas: /* About the "how it works" section */

2011-08-12T08:40:09Z

About the "how it works" section

← Older revision		Revision as of 08:40, 12 August 2011
Line 112:		Line 112:

	Just in case those haven't been considered. [[User:Eloy Lafuente (stronk7)\|Eloy Lafuente (stronk7)]] 22:13, 2 September 2009 (UTC)		Just in case those haven't been considered. [[User:Eloy Lafuente (stronk7)\|Eloy Lafuente (stronk7)]] 22:13, 2 September 2009 (UTC)



			== Brainstorm for WS Roadmap ==

			Current

			user:

			create_users()
			delete_users()
			update_users()
			get_users_by_id() - returns a list of full user objects specified by user ids (only useful for site admin accounts)
			get_course_participants_by_id() - returns a list of full user objects in specific courses (that you can see)
			get_users_by_courseid() - returns some subset of full user objects from a course (perhaps by group or capability)

			course:

			get_courses()
			create_courses()

			group:

			create_groups()
			get_groups()
			get_course_groups()
			delete_groups()
			get_groupmembers()
			add_groupmembers()
			delete_groupmembers()

			enrol:

			get_enrolled_users() - get some minimal information about the users enrolled in a course (DEPRECATED)
			get_users_courses() - get list of course ids that a user is enrolled in (if you are allowed to see that)
			role_assign()
			role_unassign()

			enrol/manual:

			manual_enrol_users()

			webservice:

			get_siteinfo_parameters()

			message:

			send_instantmessages()

			files:

			get_files()
			upload()

Stronk7: /* About the "how it works" section */

2009-09-02T22:13:20Z

About the "how it works" section

← Older revision		Revision as of 22:13, 2 September 2009
Line 108:		Line 108:
	Just two suggestions:		Just two suggestions:

	In point 1: instead of sending login + password I'd recommend sending login + hash(login and password) or something like that, just prevent sending plain password (and easily identificable). Assuming that SSL isn't a MUST, of course.		* In point 1: instead of sending login + password I'd recommend sending login + hash(login and password) or something like that, just prevent sending plain password (and easily identificable). Assuming that SSL isn't a MUST, of course.
	In point 10: together with the final response to the client with the results I'd recommend to send a renewed token, avoiding to use the same token all the time. That way, possibilities to explode a stolen token are really minimised.		* In point 10: together with the final response to the client with the results I'd recommend to send a renewed token, avoiding to use the same token all the time. That way, possibilities to explode a stolen token are really minimised.

	Just in case those haven't been considered. ~~Ciao~~ :-)		Just in case those haven't been considered. [[User:Eloy Lafuente (stronk7)\|Eloy Lafuente (stronk7)]] 22:13, 2 September 2009 (UTC)

Stronk7: /* About the "how it works" section */

2009-09-02T22:12:58Z

About the "how it works" section

← Older revision		Revision as of 22:12, 2 September 2009
Line 108:		Line 108:
	Just two suggestions:		Just two suggestions:

	In point 1: instead of sending login + password I'd recommend sending login + hash(login and password) or something like that, just prevent sending password ~~alone~~ (and easily identificable). Assuming that SSL isn't a MUST, of course.		In point 1: instead of sending login + password I'd recommend sending login + hash(login and password) or something like that, just prevent sending plain password (and easily identificable). Assuming that SSL isn't a MUST, of course.
	In point 10: together with the final response to the client with the results I'd recommend to send a renewed token, avoiding to use the same token all the time. That way, possibilities to explode a stolen token are really minimised.		In point 10: together with the final response to the client with the results I'd recommend to send a renewed token, avoiding to use the same token all the time. That way, possibilities to explode a stolen token are really minimised.

	Just in case ~~it hasn~~'t been considered. Ciao :-)		Just in case those haven't been considered. Ciao :-)

Stronk7: About the "how it works" section

2009-09-02T22:11:37Z

About the "how it works" section

← Older revision		Revision as of 22:11, 2 September 2009
Line 103:		Line 103:
	== Why the Auth Plugin? ==		== Why the Auth Plugin? ==
	Just curious what I missed - what was the reason for implementing a web services auth plugin? I agree with what Eloy said in chat - the problem with this approach is that you'd probably want to apply any restrictions that might be implemented in the plugin to be applied to users with traditional authentication? --[[User:Dan Poltawski\|Dan Poltawski]] 01:32, 3 February 2009 (CST)		Just curious what I missed - what was the reason for implementing a web services auth plugin? I agree with what Eloy said in chat - the problem with this approach is that you'd probably want to apply any restrictions that might be implemented in the plugin to be applied to users with traditional authentication? --[[User:Dan Poltawski\|Dan Poltawski]] 01:32, 3 February 2009 (CST)

			== About the "how it works" section ==

			Just two suggestions:

			In point 1: instead of sending login + password I'd recommend sending login + hash(login and password) or something like that, just prevent sending password alone (and easily identificable). Assuming that SSL isn't a MUST, of course.
			In point 10: together with the final response to the client with the results I'd recommend to send a renewed token, avoiding to use the same token all the time. That way, possibilities to explode a stolen token are really minimised.

			Just in case it hasn't been considered. Ciao :-)

Jmouneyrac at 01:32, 25 February 2009

2009-02-25T01:32:17Z

← Older revision		Revision as of 01:32, 25 February 2009
Line 103:		Line 103:
	== Why the Auth Plugin? ==		== Why the Auth Plugin? ==
	Just curious what I missed - what was the reason for implementing a web services auth plugin? I agree with what Eloy said in chat - the problem with this approach is that you'd probably want to apply any restrictions that might be implemented in the plugin to be applied to users with traditional authentication? --[[User:Dan Poltawski\|Dan Poltawski]] 01:32, 3 February 2009 (CST)		Just curious what I missed - what was the reason for implementing a web services auth plugin? I agree with what Eloy said in chat - the problem with this approach is that you'd probably want to apply any restrictions that might be implemented in the plugin to be applied to users with traditional authentication? --[[User:Dan Poltawski\|Dan Poltawski]] 01:32, 3 February 2009 (CST)

	~~== Design state at the 16 Feb 2009 ==~~
	~~Here some information about the seb services implementation at this time. --Jerome Mouneyrac, 16 February 2009 (CST)~~
	~~=== Core functions ===~~
	~~The core functions are located in different lib.php. These functions are independent of the web service structure.<br>~~
	~~My opinion: we probably need to add/modify some, but we'll do that once the clients/servers and API will be implemented.~~

	~~=== Web service API ===~~
	~~The web service API is included into every external.php file. Every moodle folder (mod/forum, user, ...) can have its own external.php file.~~
	~~==== General design ====~~
	~~These external.php files contains a class that can't be extended. The class functions are static. The class functions call the core functions. The class functions check user capability.<br>~~
	~~My opinion: the design is good. We will implement all functions once clients/servers and web services description are fully implemented/defined.~~
	~~==== Web service description====~~
	~~The external.php files contain a description array. This description array describes web service parameters (mandatory, optional, return, types) for every web service functions.<br>~~
	My opinion: if we use only third-party clients/servers as SOAP/XMLRPC Zend we don't need this description array. These clients/servers check the phpdoc in order to know the web service description. <br>
	However these description array are mandatory if we do choose to implement our own clients/servers. They are also mandatory for some third party client/server as Zend_amf. The AMF client/server need some value object class. In order to generate these VO classes, Moodle needs to know the structure of parameters/returned objects. <br>Note: we could use the phpdoc instead of the a description array. However the implementation is much more complex. For example Zend framework use a Reflection class that is not easy to understand, even less to use. I could not find any explanation how to parse the phpdoc...

	~~=== The clients/servers===~~
	~~==== REST ====~~
	REST has no defined W3C specification. W3C just define an architecture. Many REST client/server implementation are not RESTful. By RESTful I mean retrieving data should use GET, creating data POST, deleting data DELETE and updating data PUT.<br>
	~~At this moment we don't have in HEAD any RESTful client/server. The one we created is not RESTful (use only POST) and the Zend one is going to be deprecated in the futur Zend framework release.<br>~~
	My opinion: I had a look at Java REST implementation, and they use annotation on the function (@GET, @POST). That make sens that we need this kind of information about the web services functions. So if we want to build a RESTful server this information should be into the description or into the phpdoc.<br>
	~~Zend are writing some new RESTful functions but they seem to use intensively other Zend libraries. Wait and see.~~
	~~I couldn't find a RESTful client/server implementation.<br>~~
	~~At this moment our own REST server cannot manage array as parameter. We cannot for example call function to delete multiple user yet. (but it works with SOAP. XMLRPC and Zend Rest server)~~

	~~==== SOAP ====~~
	At this moment SOAP client/server, and XMLRPC client/server, using the Zend client/server are the closest working client/server we have. Their limitation are that the client need to mention the path (moodle folder) of the external.php file.<br>
	~~I created a SOAP client/server with WSDL generator. Then I discover that the Zend framework were working on the same, so I implemented another client/server using it.<br>~~
	My opinion: I think it is better to use the Zend SOAP server as their community will work to improve it and fix it. It will be good also to have a Zend SOAP server that load all Moodle function into one WSDL (no need Moodle path). Then see how are the performance. The reason for that is that the client could request only one WSDL file. Zend are also working on a way to have multiple services into the WSDL, that would allow us to still use Moodle path (good performance) and to deliver only one WSDL file to the client.<br>
	~~I don't think we should use nuSOAP as the project is for PHP4, and have less support these days.~~

	~~==== XMLRPC ====~~
	~~THe Zend client/server has good reputation, and it is easy to use. It's also using phpdoc.<br>~~
	~~My opinion: we should go for it.~~

	~~==== AMF ====~~
	Zend and Adobe released a client/server for AMF. The main problem of this solution is that require PHP value object class in order to map the parameters (and returned objects) to the Flex value objects. Either we decide to write all these value object classes for all web service functions, either we generate them (need description array)


	~~=== My overall opinion ===~~
	~~I think we should offer a SOAP and XMLRPC solution using Zend clients/servers.<br>~~
	Then come the decision to keep the web service description arrays. Some kind of description are currently needed for REST and AMF. It could be by phpdoc but it's not easy to implement. So the description array still seems mandatory (and could be useful to implement client/server for a new web service protocol)
	~~==== REST ====~~
	~~Do we want a RESTful server or not ? A RESTful server is more difficult to implement, but most important it requires some additional description about functions (is it a GET, POST, DELETE, PUT?).~~

	~~==== AMF ====~~
	~~decision can be delayed later on, Flex still should be able to communicate easily with SOAP.~~

Jmouneyrac: /* Design state at the 16 Feb 2009 */

2009-02-16T04:44:23Z

Design state at the 16 Feb 2009

← Older revision		Revision as of 04:44, 16 February 2009
Line 105:		Line 105:

	== Design state at the 16 Feb 2009 ==		== Design state at the 16 Feb 2009 ==
			Here some information about the seb services implementation at this time. --Jerome Mouneyrac, 16 February 2009 (CST)
	=== Core functions ===		=== Core functions ===
	~~Moodle web service API will call Moodle~~ core ~~functions. These~~ functions are located in different lib.php. These functions are independent of the web service structure.<br>		The core functions are located in different lib.php. These functions are independent of the web service structure.<br>
	My opinion: ~~all good. No~~ need to ~~change~~		My opinion: we probably need to add/modify some, but we'll do that once the clients/servers and API will be implemented.

	=== Web service API ===		=== Web service API ===
Line 113:		Line 114:
	==== General design ====		==== General design ====
	These external.php files contains a class that can't be extended. The class functions are static. The class functions call the core functions. The class functions check user capability.<br>		These external.php files contains a class that can't be extended. The class functions are static. The class functions call the core functions. The class functions check user capability.<br>
	My opinion: all ~~good~~.		My opinion: the design is good. We will implement all functions once clients/servers and web services description are fully implemented/defined.
	==== Web service description====		==== Web service description====
	~~These~~ external.php ~~contains~~ a description array. This description describes web service parameters (mandatory, optional, return, types) for every web service functions.<br>		The external.php files contain a description array. This description array describes web service parameters (mandatory, optional, return, types) for every web service functions.<br>
	My opinion: if we use third-party clients/servers as SOAP/XMLRPC Zend we don't need it. These clients/servers check the phpdoc in order to know the web service description. <br>		My opinion: if we use only third-party clients/servers as SOAP/XMLRPC Zend we don't need this description array. These clients/servers check the phpdoc in order to know the web service description. <br>
	However these description are mandatory if we do choose to implement our own ~~client~~/~~server~~. They are also mandatory for some third party client/server as Zend_amf. ~~This~~ AMF client/server ~~needs~~ some value object class. In order to generate these classes, Moodle needs to know the structure of parameters/returned objects. Note ~~that~~ we could use the phpdoc instead of the a description array. However the implementation ~~seems~~ much more complex. For example Zend framework use a Reflection class that is not easy to understand, even less to use. I could not find any explanation how to parse the phpdoc...		However these description array are mandatory if we do choose to implement our own clients/servers. They are also mandatory for some third party client/server as Zend_amf. The AMF client/server need some value object class. In order to generate these VO classes, Moodle needs to know the structure of parameters/returned objects. <br>Note: we could use the phpdoc instead of the a description array. However the implementation is much more complex. For example Zend framework use a Reflection class that is not easy to understand, even less to use. I could not find any explanation how to parse the phpdoc...

	=== The clients/servers===		=== The clients/servers===
	==== REST ====		==== REST ====
	REST has no defined W3C specification ~~but~~ an architecture. Many REST client/server implementation are not RESTful. By RESTful I mean ~~that~~ retrieving data should use GET, creating data POST, deleting data DELETE and updating data PUT.<br>		REST has no defined W3C specification. W3C just define an architecture. Many REST client/server implementation are not RESTful. By RESTful I mean retrieving data should use GET, creating data POST, deleting data DELETE and updating data PUT.<br>
	At this moment we don't have in HEAD any RESTful client/server. The one we created is not RESTful (use ~~mainly~~ POST) and the Zend one is going to be deprecated in the futur Zend framework release.<br>		At this moment we don't have in HEAD any RESTful client/server. The one we created is not RESTful (use only POST) and the Zend one is going to be deprecated in the futur Zend framework release.<br>
	My opinion: I had a look at Java REST implementation, and they use annotation on the function (@GET, @POST). That make sens that we need this kind of information about the web services functions. So if we want to build a RESTful server it should be into the description or into the phpdoc.<br>		My opinion: I had a look at Java REST implementation, and they use annotation on the function (@GET, @POST). That make sens that we need this kind of information about the web services functions. So if we want to build a RESTful server this information should be into the description or into the phpdoc.<br>
	Zend are writing some new RESTful functions but ~~it seems~~ to use intensively ~~their~~ other ~~library~~. Wait to see.		Zend are writing some new RESTful functions but they seem to use intensively other Zend libraries. Wait and see.
	I couldn't find a RESTful implementation.<br>		I couldn't find a RESTful client/server implementation.<br>
	At this moment our own REST server cannot manage array as parameter. We cannot for example call function to delete multiple user yet.		At this moment our own REST server cannot manage array as parameter. We cannot for example call function to delete multiple user yet. (but it works with SOAP. XMLRPC and Zend Rest server)

	==== SOAP ====		==== SOAP ====
	At this moment SOAP client/server, as XMLRPC client/server, using the Zend client/server are the ~~close~~ working client/server we have. Their limitation are that the client need to mention the path (moodle folder) of the external.php file.<br>		At this moment SOAP client/server, and XMLRPC client/server, using the Zend client/server are the closest working client/server we have. Their limitation are that the client need to mention the path (moodle folder) of the external.php file.<br>
	I created a SOAP client/server with WSDL generator. Then I discover that the Zend framework were working on the same, so I implemented another client/server using it.<br>		I created a SOAP client/server with WSDL generator. Then I discover that the Zend framework were working on the same, so I implemented another client/server using it.<br>
	My opinion: I think it is better to use the Zend SOAP server as their community will work to improve it and fix it. It will be good also to have a Zend SOAP server that load all Moodle function into one WSDL (no need Moodle path). Then see how are the performance. The reason for that is that the client could request only one WSDL file. Zend are also working on a way to have multiple ~~service~~ into the WSDL, that would allow us to still use Moodle path (good performance) and to deliver only one WSDL file to the client.<br>		My opinion: I think it is better to use the Zend SOAP server as their community will work to improve it and fix it. It will be good also to have a Zend SOAP server that load all Moodle function into one WSDL (no need Moodle path). Then see how are the performance. The reason for that is that the client could request only one WSDL file. Zend are also working on a way to have multiple services into the WSDL, that would allow us to still use Moodle path (good performance) and to deliver only one WSDL file to the client.<br>
	I don't think we should use nuSOAP as the project is for PHP4, and have less support these days.		I don't think we should use nuSOAP as the project is for PHP4, and have less support these days.

Line 139:		Line 140:

	==== AMF ====		==== AMF ====
	Zend and Adobe released a client/server for AMF. The main problem of this solution is that require PHP value object class in order to map the ~~parameter~~ (and returned ~~object~~) to the Flex value ~~object~~. Either we decide to write all these value object ~~class~~ for all web ~~services~~ functions either we generate them (need ~~some~~ description)		Zend and Adobe released a client/server for AMF. The main problem of this solution is that require PHP value object class in order to map the parameters (and returned objects) to the Flex value objects. Either we decide to write all these value object classes for all web service functions, either we generate them (need description array)


	=== My overall opinion ===		=== My overall opinion ===
	I think we should offer a SOAP and XMLRPC solution using Zend clients/servers.<br>		I think we should offer a SOAP and XMLRPC solution using Zend clients/servers.<br>
	Then come the decision to keep the web service description arrays. Some kind of description are currently needed for REST and AMF. It could be by phpdoc but it's not easy to implement.		Then come the decision to keep the web service description arrays. Some kind of description are currently needed for REST and AMF. It could be by phpdoc but it's not easy to implement. So the description array still seems mandatory (and could be useful to implement client/server for a new web service protocol)
	==== REST ====		==== REST ====
	Do we want a RESTful server or not ? A RESTful server is more difficult to implement, but most important it requires ~~for~~ additional description about ~~the function~~ (is it a GET, POST, DELETE, PUT?).		Do we want a RESTful server or not ? A RESTful server is more difficult to implement, but most important it requires some additional description about functions (is it a GET, POST, DELETE, PUT?).

	==== AMF ====		==== AMF ====
	decision can be delayed later on, Flex still should be able to communicate easily with SOAP.		decision can be delayed later on, Flex still should be able to communicate easily with SOAP.

Jmouneyrac: /* Core functions */

2009-02-16T04:29:35Z

Core functions

← Older revision		Revision as of 04:29, 16 February 2009
Line 106:		Line 106:
	== Design state at the 16 Feb 2009 ==		== Design state at the 16 Feb 2009 ==
	=== Core functions ===		=== Core functions ===
	Moodle web service API will call Moodle core functions. These functions are located in different lib.php. These functions are independent of the web service structure.		Moodle web service API will call Moodle core functions. These functions are located in different lib.php. These functions are independent of the web service structure.<br>
	My opinion: all good. No need to change		My opinion: all good. No need to change

Jmouneyrac: /* Design state at the 16 Feb 2009 */

2009-02-16T04:28:54Z

Design state at the 16 Feb 2009

← Older revision		Revision as of 04:28, 16 February 2009
Line 111:		Line 111:
	=== Web service API ===		=== Web service API ===
	The web service API is included into every external.php file. Every moodle folder (mod/forum, user, ...) can have its own external.php file.		The web service API is included into every external.php file. Every moodle folder (mod/forum, user, ...) can have its own external.php file.
	==== General design =====		==== General design ====
	These external.php files contains a class that can't be extended. The class functions are static. The class functions call the core functions. The class functions check user capability.<br>		These external.php files contains a class that can't be extended. The class functions are static. The class functions call the core functions. The class functions check user capability.<br>
	My opinion: all good.		My opinion: all good.