We are currently in the process of assessing the requirements for a comprehensive external API. At present, web services represent the only supported external API, though they will eventually be deprecated and replaced by our new system once it is complete.
Web services allow external systems to control your Totara site. They can be enabled under Quick-access menu > Configure features.
It is recommended that you only enable web services if you intend to use them. Since this feature allows external systems to control your site it could leave your Totara vulnerable if you have web services enabled but don't use them.
By going to Plugins > Web services from the quick-access menu you can access all of the settings associated with web services.
The Overview page walks you through the necessary steps for setting up web services. This includes setting up mobile devices, enabling access for external systems, and setting up users as clients.
If you want to see the API documentation for your site, navigate to Quick-access menu > Plugins > Web services > API Documentation.
As different Totara sites can choose to enable and restrict certain web services, then the API documentation becomes tailored to an individual site.
You can save the API documentation as a PDF by clicking the Print all button. This is helpful if you need to share it with someone outside of your site.
To view or edit the functions being carried out by external services enabled on your site, you can go to Quick-access menu > Plugins > Web services > External services.
In either the Built-in services or Custom services tables, you can click Function next to a particular service to view all the functions being carried out by that service or click Edit to customise the functions that web service is carrying out.
To add a new external service:
- Click the Add link, located underneath the tables Built-in services and Custom services tables.
- Fill out the form, you can click Show more... to see additional options. Mandatory fields are marked with an asterisk (*).
- Once you've set up everything you need, click Add service to save this new external service (or click Cancel if you no longer wish to add the service).
The Manage protocols page allows you to enable or disable various web service protocols. Available protocols are: AMF, REST, SOAP, and XML-RPC.
It is recommended for security reasons that you only enable protocols that are in use by your site.
If you are either a developer yourself or you are working with a web services client developer then you will want to enable Web services documentation. This is done by ticking the box alongside this option and clicking Save changes.
You can generate a unique token for any users in the system - this is the only way to generate tokens for admin users.
The Manage token page will show you a list all the currently issued tokens; you can use the delete link to get rid of any of these. The list only shows the details of the current tokens, and not the tokens themselves (to maintain their security and integrity).
To create a new token:
- Click the Add link under the list of tokens.
- Complete the mandatory fields (marked with an asterisk), you can also add an IP restriction and Valid until date.
- Once you have entered all the required information click Save changes to generate the token.
You will be shown the newly created token, which will need to be copied before closing the page as it will not be shown again.