Submit a ticket My Tickets
Welcome
Login

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 



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

Picture of External service menu with Add service button circled in orange



Step 2: Add Functions to the Service 

Picture of Add functions to the service selection with Add functions link circled in orange

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

Picture of Assign role to user settings with Add functions button circled in orange


  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.

    Picture of Custom services list with line item Assign role to user > Authorized users link circled in orange

  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

Picture of Manage protocols menu with REST protocol circled in orange


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
    Picture of Create Token settings with Save changes button circled in orange
  5. You will now see your new access token listed
  6. Copy the token for use in the next section

    Picture of Manage Tokens page with newly created token circled in orange

 

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:

Parameter

Value

wstoken

The token you copied from earlier

wsfunction

The name of the function you want to perform, e.g. "core_role_assign_roles"

moodlewsrestformat

The format you want the results in. Options are "json" or "xml"



Wrapping it all up

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

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.