Web services FAQ: Difference between revisions
From MoodleDocs
No edit summary |
(ja link) |
||
| (15 intermediate revisions by 3 users not shown) | |||
| Line 1: | Line 1: | ||
{{Web services}} | |||
This document lists some popular questions from the [http://moodle.org/mod/forum/view.php?id=6971 Web Services forum]. | This document lists some popular questions from the [http://moodle.org/mod/forum/view.php?id=6971 Web Services forum]. | ||
== What is the difference between web services and | == What is the difference between web services and MNet == | ||
[[MNet]] is used to authenticate some users from a Moodle A site into a Moodle B site. | |||
Web services are functions that can be called by external applications (via SOAP, XML-RPC, REST or AMF). | |||
== I see the term "Web services" used in different ways, what does it mean? == | == I see the term "Web services" used in different ways, what does it mean? == | ||
| Line 12: | Line 13: | ||
# A particular action (like creating a user) is known as a Web service '''function'''. | # A particular action (like creating a user) is known as a Web service '''function'''. | ||
# The admin can enable groups of these functions for outside use, and these are known as a "Web service". | # The admin can enable groups of these functions for outside use, and these are known as a "Web service". | ||
== Where is the Web Service API documented? == | == Where is the Web Service API documented? == | ||
| Line 18: | Line 18: | ||
Since different Moodle sites can extend or restrict the API, and the API will evolve over time, the best way to see the exact API for a particular Moodle site is to look at the automatically generated documentation. | Since different Moodle sites can extend or restrict the API, and the API will evolve over time, the best way to see the exact API for a particular Moodle site is to look at the automatically generated documentation. | ||
# | '''Full API documentation''' | ||
# | # Connect as admin | ||
# | # Go to Administration Settings block > Plugins > Web services > API documentation | ||
'''Specific documentation to a user''' | |||
# Connect as admin, enable web service, create a service and add some Moodle functions to it. Also see [[How_to_create_and_enable_a_web_service]]. | |||
# connect as non admin, and access the service documentation on your [[How_to_get_a_security_key|security keys page]]. | |||
== Why are there not many functions in the API? == | == Why are there not many functions in the API? == | ||
| Line 26: | Line 30: | ||
We have been very careful when adding new functions because we don't want to be changing the API functions once they are implemented. The ones we have in Moodle 2.0 are the most commonly requested ones (for users, courses, groups and enrolments). | We have been very careful when adding new functions because we don't want to be changing the API functions once they are implemented. The ones we have in Moodle 2.0 are the most commonly requested ones (for users, courses, groups and enrolments). | ||
We will add more functions to core over time, based on contributions from the community and feature requests. See the | We will add more functions to core over time, based on contributions from the community and feature requests. See the [[:dev:Web_services_Roadmap|web service roadmap]]. | ||
You can also extend the API on your own Moodle site by creating your own API functions (see next question). | You can also extend the API on your own Moodle site by creating your own API functions (see next question). | ||
| Line 32: | Line 36: | ||
== How can I create a new web service function? == | == How can I create a new web service function? == | ||
The easiest and recommended way to add a web service is to write a new Moodle local plugin and to implement the web service functions there. | The easiest and recommended way to add a web service is to write a new Moodle local plugin and to implement the web service functions there. The Moodle administrator will just need to add the plugin in Moodle (copy the files in /local/), the web service functions will be automatically added. Please read /local/readme.txt for more information about plugin development. Finally read [[:dev:Creating_a_web_service_and_a_web_service_function|how to implement a web service and a web service function]]. | ||
== How can I set up a web service? == | == How can I set up a web service? == | ||
* See the | * See the document [[How_to_create_and_enable_a_web_service| How to create and enable a web service]]. | ||
* | * ''Settings > Site administration > Plugins > Web services > Overview'' explains two use cases. | ||
* Finally you can | * Finally ask questions on the [http://moodle.org/mod/forum/view.php?id=6971 Web Services forum] | ||
== Does the Moodle SOAP server work with JAVA or .NET? == | |||
Unfortunately the generated WSDL isn't currently compatible with JAVA or .NET. See MDL-28988 and MDL-28989 for plans to create a JAVA-compatible SOAP WSDL. | |||
== How to get a user token from an external application? == | |||
you can generate and retrieve user tokens with the /login/token.php file => [[:dev:Creating_a_web_service_client#How_to_get_a_user_token|How to get a user token]] | |||
== What is the 'Access control exception' error == | |||
It means that one of this admin setting has failed: | |||
* authorised user: ip restriction fails to authenticate the user (Administration > Plugins > Web services > Manage services > Authorized users > click on user full name) | |||
* authorised user: valid date is expired (Administration > Plugins > Web services > Manage services > Authorized users > click on user full name) | |||
* admin created the token: ip restriction fails to authenticate the user (Administration > Plugins > Web services > Manage tokens > check the status) | |||
* admin created the token: valid date is expired (Administration > Plugins > Web services > Manage tokens > check the status) | |||
* the user is not listed in the authorized list (Administration > Plugins > Web services > Manage services > Authorized users) | |||
* the user hasn't the required capability (Administration > Plugins > Web services > Manage services > Edit service) | |||
* site in maintenance mode | |||
* user is suspended | |||
* user is not confirmed | |||
* user is deleted | |||
* the user authentication is set to nologin (edit the user profile) | |||
* password expired (most likely happens with external authentication like LDAP) | |||
* web service disabled (Administration > Advanced features) | |||
* user doesn't have the capability to use the used web service protocol (user should have the capability 'webservice/use:xmlrpc'/'webservice/use:rest'/..., on SYSTEM context). | |||
* the user token doesn't exist | |||
* the web service function is not included in the service | |||
Since Moodle 2.2, if the administrator turns Moodle debug mode >= NORMAL, then an explicit error message will be returned. | |||
==See also== | |||
* Using Moodle [http://moodle.org/mod/forum/view.php?id=6971 Web Services forum] | |||
[[Category:MNet]] | [[Category:MNet]] | ||
[[Category:FAQ]] | [[Category:FAQ]] | ||
[[ja:ウェブサービスFAQ]] | |||
Latest revision as of 22:14, 3 December 2013
This document lists some popular questions from the Web Services forum.
What is the difference between web services and MNet
MNet is used to authenticate some users from a Moodle A site into a Moodle B site.
Web services are functions that can be called by external applications (via SOAP, XML-RPC, REST or AMF).
I see the term "Web services" used in different ways, what does it mean?
- The entire system in Moodle is referred to as the Moodle Web Service system.
- A particular action (like creating a user) is known as a Web service function.
- The admin can enable groups of these functions for outside use, and these are known as a "Web service".
Where is the Web Service API documented?
Since different Moodle sites can extend or restrict the API, and the API will evolve over time, the best way to see the exact API for a particular Moodle site is to look at the automatically generated documentation.
Full API documentation
- Connect as admin
- Go to Administration Settings block > Plugins > Web services > API documentation
Specific documentation to a user
- Connect as admin, enable web service, create a service and add some Moodle functions to it. Also see How_to_create_and_enable_a_web_service.
- connect as non admin, and access the service documentation on your security keys page.
Why are there not many functions in the API?
We have been very careful when adding new functions because we don't want to be changing the API functions once they are implemented. The ones we have in Moodle 2.0 are the most commonly requested ones (for users, courses, groups and enrolments).
We will add more functions to core over time, based on contributions from the community and feature requests. See the web service roadmap.
You can also extend the API on your own Moodle site by creating your own API functions (see next question).
How can I create a new web service function?
The easiest and recommended way to add a web service is to write a new Moodle local plugin and to implement the web service functions there. The Moodle administrator will just need to add the plugin in Moodle (copy the files in /local/), the web service functions will be automatically added. Please read /local/readme.txt for more information about plugin development. Finally read how to implement a web service and a web service function.
How can I set up a web service?
- See the document How to create and enable a web service.
- Settings > Site administration > Plugins > Web services > Overview explains two use cases.
- Finally ask questions on the Web Services forum
Does the Moodle SOAP server work with JAVA or .NET?
Unfortunately the generated WSDL isn't currently compatible with JAVA or .NET. See MDL-28988 and MDL-28989 for plans to create a JAVA-compatible SOAP WSDL.
How to get a user token from an external application?
you can generate and retrieve user tokens with the /login/token.php file => How to get a user token
What is the 'Access control exception' error
It means that one of this admin setting has failed:
- authorised user: ip restriction fails to authenticate the user (Administration > Plugins > Web services > Manage services > Authorized users > click on user full name)
- authorised user: valid date is expired (Administration > Plugins > Web services > Manage services > Authorized users > click on user full name)
- admin created the token: ip restriction fails to authenticate the user (Administration > Plugins > Web services > Manage tokens > check the status)
- admin created the token: valid date is expired (Administration > Plugins > Web services > Manage tokens > check the status)
- the user is not listed in the authorized list (Administration > Plugins > Web services > Manage services > Authorized users)
- the user hasn't the required capability (Administration > Plugins > Web services > Manage services > Edit service)
- site in maintenance mode
- user is suspended
- user is not confirmed
- user is deleted
- the user authentication is set to nologin (edit the user profile)
- password expired (most likely happens with external authentication like LDAP)
- web service disabled (Administration > Advanced features)
- user doesn't have the capability to use the used web service protocol (user should have the capability 'webservice/use:xmlrpc'/'webservice/use:rest'/..., on SYSTEM context).
- the user token doesn't exist
- the web service function is not included in the service
Since Moodle 2.2, if the administrator turns Moodle debug mode >= NORMAL, then an explicit error message will be returned.
See also
- Using Moodle Web Services forum
