Web Services

Web Services

Moodle web services provide an API that allows external applications to interact with Moodle programmatically. This is the foundation for the official Moodle mobile app, third-party integrations, and custom development. Web services support REST, XML-RPC, and SOAP protocols.

Enabling Web Services

Web services are disabled by default. To enable them:

1. Navigate to Site administration > General > Advanced features
2. Check Enable web services and save
3. Navigate to Site administration > Server > Web services > Overview
4. Follow the setup checklist provided on this page

Step-by-Step Configuration

Step 1: Enable Protocols

Navigate to Site administration > Server > Web services > Manage protocols. Enable the protocols you need:

• REST: The most commonly used protocol. Simple, efficient, and widely supported. Recommended for most integrations.
• XML-RPC: Legacy protocol, still used by some older integrations
• SOAP: Enterprise protocol used in some institutional integrations

Step 2: Create a Web Service

1. Go to Site administration > Server > Web services > External services
2. Click Add to create a new external service
3. Enter a name and description
4. Choose whether it is Enabled and whether Authorised users only (recommended)
5. Save the service

Step 3: Add Functions to the Service

Click on Functions for the newly created service. Add the specific API functions the service needs access to. Common functions include:

• core_user_get_users — Retrieve user information
• core_course_get_courses — Get course details
• core_enrol_get_enrolled_users — List enrolled users
• mod_assign_get_assignments — Get assignment information
• core_user_create_users — Create user accounts
• enrol_manual_enrol_users — Enrol users in courses
• gradereport_user_get_grade_items — Retrieve grade data

Step 4: Create a User for the Service

Create a dedicated user account for the web service (do not use admin accounts). Assign the appropriate role with the necessary capabilities.

Step 5: Assign the User to the Service

Under the external service settings, add the web service user to the Authorised users list.

Step 6: Create a Token

Navigate to Site administration > Server > Web services > Manage tokens. Create a token for the web service user, associating it with the external service. You can optionally set:

• Valid until: Expiration date for the token
• IP restriction: Limit token usage to specific IP addresses (highly recommended)

Making API Calls

Example REST API call using curl:

# Get site info
curl "https://yourmoodle.example.com/webservice/rest/server.php?wstoken=YOUR_TOKEN&wsfunction=core_webservice_get_site_info&moodlewsrestformat=json"

# Get users by field
curl -X POST "https://yourmoodle.example.com/webservice/rest/server.php" 
  -d "wstoken=YOUR_TOKEN" 
  -d "wsfunction=core_user_get_users_by_field" 
  -d "moodlewsrestformat=json" 
  -d "field=email" 
  -d "values[0]=user@example.com"

# Create a user
curl -X POST "https://yourmoodle.example.com/webservice/rest/server.php" 
  -d "wstoken=YOUR_TOKEN" 
  -d "wsfunction=core_user_create_users" 
  -d "moodlewsrestformat=json" 
  -d "users[0][username]=newuser" 
  -d "users[0][password]=Password1!" 
  -d "users[0][firstname]=John" 
  -d "users[0][lastname]=Doe" 
  -d "users[0][email]=john@example.com"

Mobile Web Services

The Moodle mobile app uses a pre-configured external service called Moodle mobile web service. To enable mobile access:

1. Go to Site administration > General > Mobile app > Mobile settings
2. Enable Enable web services for mobile devices
3. The mobile service and its functions are automatically configured

Security Considerations

• Use token-based authentication instead of passing passwords
• Restrict tokens by IP address wherever possible
• Set token expiration dates
• Grant only the minimum required functions to each service
• Use HTTPS for all web service communications
• Regularly audit active tokens and revoke unused ones
• Monitor web service logs for suspicious activity

API Documentation

Moodle provides auto-generated API documentation at Site administration > Server > Web services > API Documentation. This page lists all available functions with their parameters, return types, and descriptions. Use this as a reference when developing integrations.