Using the Web Services Application Programming Interface (API) in Moodle

Overview

Moodle's Web Services Application Programming Interface (API) allows external systems to perform operations that are normally only accessible from within a Moodle site. This guide will show you how to create an external service in Moodle, how to generate a token for the service, and how to call the service with a POST request from outside the Moodle system. We will create an external service that can be used to assign users to roles in various contexts throughout the Moodle site.

Before You Begin 

• Writing a New Service (Moodle Developer Resources)

• Using Web Services 

• Creating a Web Service Client

Steps

1. Create an external service

2. Add functions to the service

3. Assign role to user

4. Obtain an access token

5. Call the API from an external service

Step 1: Create an External Service

1. On your Moodle site, click Site Administration > Plugins > Web services > External services

2. Click the Add link at the bottom of the page beneath the Custom services heading

3. Type a name for your service that describes what it can do in basic terms. Check the Enabled and Authorized users only boxes and click the Add service button
   
   

Step 2: Add Functions to the Service 

Search for the function(s) you wish to use with this external service by name in the search box, and then click the name of the function to add it to the service.

Note: You may add as many functions as you like to the service, but it is best to include only functions that are necessary to your use of this service. For a complete list of available functions, visit the Web Services API documentation page on your Moodle site by clicking Site Administration > Plugins > Web services > API Documentation.

Step 3: Assign Role to User

1. Return to the External services page and you should see the service you just created listed under the Custom services heading. Click the Authorized users link.
   
   
   
   
2. Select the authorized user and click Add. If the user is missing any permissions to perform the service's functions, those permissions will be listed at the bottom of this page.
3. Navigate to Site Administration > Plugins > Web services > Manage protocols
4. Make sure that the REST protocol is enabled
   1. If it is disabled, click the eye icon next to it to enable it

The external service is now properly configured.

Step 4: Obtain an Access Token

Before you can use the external service, you must create an access token. This token forms part of your external API call and functions as a password that proves your call has the right to manipulate data on your Moodle site.

1. Navigate to Site Administration > Plugins > Web services > Manage tokens
2. Click the Add link at the bottom of the page
3. Select the authorized user you chose in the previous section and choose the appropriate external service from the drop-down menu
4. Click the Save changes button
   
   
5. You will now see your new access token listed
6. Copy the token for use in the next section
   
   

Step 5: Call the API from an External Service

To access the external service you created earlier, you need to send a POST request to the appropriate uniform resource locator (URL) for your Moodle site. The URL format is:

• https://<your-domain-name>/webservice/rest/server.php

The necessary parameters are:

Wrapping it all up

Now you know the basics of how to use the Web Services Application Programming Interface (API) in Moodle. 

For more information on this topic please visit:

• Moodle Developer Resource Centre 
• Moodle docs:
  • Web services
  • Workplace Web services
  • Using web services
  • Web service API functions
  • Writing a new service