9.7. Web services

Administration → Extensions → Web services

Note

Web services are only accessible by site administrators.

Web services allow you to connect your Mahara site with other applications that have web services / APIs as well. It might require some configuration or the development of specific web services functions to accomplish the integration you are looking for. The Mahara web services are a framework that makes it possible to develop additional APIs without having to do a great deal more than defining a function that exposes the required functionality, and the associated interface definition.

In order to use web services, your site must use a SSL certificate.

9.7.1. Configuration

Administration → Extensions → Web services → Configuration

On this page you set up various web services rules and enable or disable them.

9.7.1.1. Web services master switch and switching protocols on and off

You can enable web services globally and then configure protocols individually to suit your needs. Once a protocol is enabled, it can be used for all functions, users and tokens.

Switch web services or individual protocols on and off

1. Switch web services on or off: If set to “On”, web services are available to be used on your site.

   Note

   If you set the master switch to “Off”, any activated individual protocols under “Switch protocols on and off” are turned off and would need to be enabled manually again.

2. SOAP: Allow this protocol if you want to be able to use the Simple Object Access Protocol.

3. XML-RPC: Set this to “On” if you want to make remote procedure calls to XML content. This protocol is used by MNet.

   Note

   As long as MNet is supported in Mahara, you can use that to configure your connection to Moodle.

4. REST: Allow the REpresentational State Transfer protocol by turning this setting on. The REST interface also supports JSON authentication.

5. OAuth: If you want to use the OAuth (Open Authentication) protocol, turn this setting on.

9.7.1.2. Networking certificates

In this section, the public key of your Mahara certicate that is created on Administration → Configure site → Networking is displayed for convenience.

9.7.1.3. Manage service groups

Service groups are the unit of allocation of access to a user (simple authentication) or user token. They are a collection of functions. Mahara already comes with a series of service groups and functions that you can configure. More service groups can be added.

Overview of the available service groups and their basic settings

1. Service: The service group under which a number of related functions are grouped that you can enable or disable.

2. Component: The area through which a service group is available. It is generally “webservice”.

3. Enabled: If a service group is enabled, you see the Enabled icon . If it is not enabled, you see the Disabled icon .

4. Authorised users only: If the service group can be used by people who log in with a username and password, you see the Enabled icon . If it is not possible to use it as such a user, you see the Disabled icon .

5. User token access: You see the Enabled icon if access to the functions of this group requires a user token. If access via a user token is not allowed, you see the Disabled icon .

6. Functions: This is a list of functions that are associated with the service group.

   Note

   Clicking on one of the functions takes you to the web services documentation for this function. More information about the web service function is available there including a description of the functions API, input and output parameters, and error handling.

7. Click the Edit button to make changes to the service group as described below.

8. Click the Delete button to completely remove the service group.

   Note

   In many cases you may not want to delete the web service group entirely as you would need to re-create it and associate functions with it if you required it at a later stage. Disabling the group would often be sufficient.

9. If you want to create a new service group, add it in this field and click the Add button. You can then see your new group in the list of service groups and configure it by clicking the Edit button next to it.

When you selected the service group you want to edit, you see the following screen.

Edit the settings of a service group

1. Service: Set this to “On” if you want to use this service group. You can tweak the individual functions below.

2. Authorised users only: Set this to “On” if only people with a username and password should be affected by this service group.

3. User token access: Set this to “On” if you want users to have individual tokens in order to access certain functionalities.

   Note

   The user token access gives the enitre Mahara userbase the possibility to make use of the API. Therfore generally, it should be restricted to service groups that give access to user-focused functions like mahara_user_get_my_user for the current user’s own details.

4. The name of the function.

5. Enabled: This setting enables or disables the use of this function.

6. Class name: The name of the class that is part of the function.

7. Method name: The name of the method that is being called. The link takes you to the web services documentation for that method.

8. Click the Save button when you are finished making your changes, or click the Back button if you want to cancel the changes.

9.7.1.4. Manage service access tokens

You can generate access tokens for individual users and associate service groups to which that user shall have access.

Overview of the access tokens

1. Username: Type a username and click the Generate token button for a new access token to be created for that user. You are taken to a screen where you can associate a service group to this token (see below). You can only enter one username.

   Note

   You can either start typing the name or the username of a person registered on your site. You will receive suggestions for names as you type.

2. Token: The token that was generated for a particular user.

3. Institution: Lists the institution in which the user is a member.

4. User: The username is displayed and linked to the user’s settings page in the administration.

5. Service: The service group for which the token was generated.

6. Enabled: If this service group is enabled, you see the Enabled icon . If it is not enabled, you see the Disabled icon .

7. Web services security: If the web services security is enabled, you see the Enabled icon . Otherwise, you see the Disabled icon .

8. Functions: This is a list of all the functions that the token has access to for the selected service.

9. Click the Edit button to make changes to the settings.

10. Click the Delete button to remove the token.

When you create a token for a user, you need to provide some additional information.

Configure a service access token

1. Verify that you are editing the correct token.

2. Institution: Select the institution of the user.

3. Username: Verify that you have the correct username for which you want to set up a token.

4. Service: Choose the service group from the drop-down list for which you want to enable the token. Only services that allow user token access can be chosen.

5. Enabled: The token is automatically enabled when the service group is enabled.

   Note

   If you want to disable a service group, please do so in the section Manage service groups.

6. Authorised users only: This checkbox is not used in this context because here you create a token.

7. Functions: A list of functions that the token has access to.

   Note

   When you change the service, the list of functions is not automatically updated. You only see the updated list when you save the page.

8. Enable web services security (XML-RPC only): This feature is only available for XML-RPC based authentication.

9. Public key: Enter the public key for added web service security (only for XML-RPC based authentication).

10. Public key expires: Date on which the public key that you entered expires. The date is only updated once you save the form.

11. Click the Save button to save your changes or the Back button to cancel your changes.

9.7.1.5. Manage service users

If you do not wish to use a token for your users, but give them access to functions via their usernames, you should choose this option. Users must:

• only be configured once.

• have the “webservice” authentication method in an institution in which they are a member.

  Note

  Users with the authentication method “webservice” can only access Mahara via web services and cannot use the standard login form.

Manage service users overview section

1. Username: Type a username and click the Add button. You are taken to a screen where you can associate a service group to that user (see below). You can only enter one username.

   Note

   You can either start typing the name or the username of a person registered on your site. You will receive suggestions for names as you type.

2. User: The username is displayed of the user for whom you configured a service group. It is linked to the user’s account settings page in the administration.

3. Institution: Lists the institution in which the user is a member.

4. Service: The service group that is associated with the user.

5. Enabled: If this service group is enabled, you see the Enabled icon . If it is not enabled, you see the Disabled icon .

6. Web services security: If the web services security is enabled, you see the Enabled icon . Otherwise, you see the Disabled icon .

7. Functions: This is a list of all the functions that the user has access to for the selected service.

8. Click the Edit button to make changes to the settings.

9. Click the Delete button to remove the user from the access to the associated service group.

When you add a user, you need to provide some additional information.

Associate a user with a specific service group

1. The username is displayed.

2. Institution: Verify that the institution of the user is correct. If it is not, you can change the institution on the user’s account settings page.

3. Username: Verify that you have the correct username for which you want to set up a token.

4. Service: Choose the service group from the drop-down list to which you want to give the user access. Only services that allow access via a username can be chosen.

5. Enabled: The settings are automatically enabled when the service group is enabled.

   Note

   If you want to disable a service group, please do so in the section Manage service groups.

6. Authorised users only: This checkbox is selected automatically when the service group is configured to allow access via a username.

7. Functions: A list of functions that the user has access to.

   Note

   When you change the service, the list of functions is not automatically updated. You only see the updated list when you save the page.

8. Enable web services security (XML-RPC only): This feature is only available for XML-RPC based authentication.

9. Public key: Enter the public key for added web service security (only for XML-RPC based authentication).

10. Public key expires: Date on which the public key that you entered expires. The date is only updated once you save the form.

11. Click the Save button to save your changes or the Back button to cancel your changes.

9.7.2. OAuth service registration

Administration → Extensions → Web services → OAuth

OAuth service access is configured separately. This enables the selection of an institution and service definition, for which a consumer key and secret will be generated automatically.

Register an OAuth service

1. Application: Give your application that you want to add a name.
2. Choose which institution shall have access to your chosen application via OAuth.
3. Choose the service group that you want to associate with this application.
4. Click the Add button to create the OAuth authentication for the seleced service. You are taken to a screen where you can configure your application (see below).
5. Application: Lists the applications that are connected via OAuth.
6. Owner: User who has set up the OAuth service.
7. Consumer key: The consumer key for the OAuth service.
8. Consumer secret: The consumer secret for the OAuth service.
9. Enabled: If the application is enabled, you see the Enabled icon . If it is not enabled, you see the Disabled icon .
10. Callback URI: The callback URI for the application.
11. Click the Edit button to make changes to the settings.
12. Click the Delete button to remove the application so it cannot connect anymore to Mahara via OAuth.

When you want an application to connect via OAuth to Mahara, you need to provide some more information.

Configure an OAuth service

1. Server key: The consumer key for the OAuth service.

2. Consumer secret: The consumer secret for the OAuth service.

3. Application title: Give your application that you want to add a name.

4. Service owner: User who has set up the OAuth service.

5. Appliation URI: URI of the application.

6. Callback URI: The callback URI for the application.

7. Institution: Select the institution for which you want to set up OAuth.

8. Service: Select the service group that you want to set up for OAuth.

9. Enabled: The application is automatically enabled when OAuth is enabled.

10. Functions: A list of functions that the application has access to.

    Note

    When you change the service, the list of functions is not updated automatically. You only see the updated list when you save the page.

11. Click the Save button to save your changes or the Back button to cancel your changes.

9.7.3. Web services logs

Administration → Extensions → Web services → Web services logs

You can view the logs from the web services and narrow you search so you only see the relevant information.

Search the web services logs

1. User: Type the username of the person for whom you want to see the logs. You can only enter one username.

   Note

   You can either start typing the name or the username of a person registered on your site. You will receive suggestions for names as you type.

2. Protocol: Select the web services protocol that is associated with the user. You can only see the protocols that are enabled.

3. Auth type: Choose the type of authentication that you selected for the user. The options are:

   • All: Display the logs for any authentication type.
   • Token: Only display logs when the user has a user token.
   • User: Display the logs when the user uses the username for the web service.
   • OAuth: Select this option if you only want to see logs when the user logs in via OAuth.

4. Function: Search for the function that you are interested in.

5. Only errors: Tick this checkbox if you only want to see log information that contains an error.

6. Click the Go button to start your search.

7. User: Display the username of the user that you searched on.

8. Institution: Display the name of the institution in which the user is a member.

9. Protocol: Show the protocol that is associated with the user for the chosen context.

10. Authentication type: Show the authentication type that is associated with the user.

11. Function: Display the function you searched on.

12. Time taken: The time it took to fetch the log.

13. When: Display the date that the log entry was produced. You can change the sort order for this column.

14. Info: Error messages are displayed here.

9.7.4. Web services test client

Administration → Extensions → Web services → Web services test client

The test client gives you the opportunity to test your settings. Please beware that the functions are executed for real on the system.

Web services test client

Note

When you start the configuration, you only see the protocol and the authentication type if you only have one protocol selected. The other fields are revealed once you made a decision on what to test.

1. Protocol: You only see the web services protocols that are currently enabled. If you see more than one, select the one that you want to test.
2. Authentication type: Select the authentication type that you would like to include in your test.
3. Service: Choose the service group that you want to test.
4. Functions: Select the function that you want to include in your test.
5. wstoken: Enter the web services token for the user that you want to test.
6. Click the Execute button if you want to run the test or click the Cancel button if you want to abort the test.

Once the test has run, the results of the test are displayed on the screen.

9.7.5. Application connections

Administration → Extensions → Web services → Application connections

This is an overview page of all the connections that you have allowed either via personal user tokens or OAuth access tokens.

Overview of the application connections

1. The section Personal user tokens displays all the tokens that you have generated for individual users and whether they have been accessed or not amongst others.
2. Service access: This column displays the service group for which you created a token.
3. Enabled: If the service group is enabled, you see the Enabled icon . If it is not enabled, you see the Disabled icon .
4. Token: The token is displayed here.
5. Functions: The functions that are part of the service group are listed and linked. The links go to the web services documentation for the function that you selected.
6. Last access: Lists the date and time of the last use of the token.
7. Expires: Shows the expiry date of the token.
8. Click the Generate button to generate a new random token.
9. Click the Delete button to delete the token. The user group and functions are still available. You can then click the Generate button to create a new token.
10. In the OAuth access tokens section you see any tokens generated to be used with OAuth.