Moodle API

A ruby wrapper for Moodle's web service functions.

Installation

Add this line to your application's Gemfile:

gem 'moodle-api'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install moodle-api

Usage

Configuration

Different ways to configure gem.

# Pass block to configure
 Moodle::Api.configure do|c|
  c.host = 'http://my_moodle_instance.com'
  c.token = 'mytoken'
end

# Set configuration values individually
Moodle::Api.configuration.host = 'http://my_moodle_instance.com'
Moodle::Api.configuration.token = 'mytoken'

# Pass options hash to configure
Moodle::Api.configure({host: 'http://my_moodle_instance.com', token: 'mytoken'})

# The client can also be instantiated and used.
client = Moodle:Client.new({host: 'http://my_moodle_instance.com', token: 'mytoken'})

client.make_request(:function_name_here, my_params)

Moodle requires users to expose web service functions in order for them to be used. A MoodleError exception will be raised if a function with the incorrect name is called

Calling a service

All web services are available by calling

Moodle::Api.function_name_here(my_parameters)

New functions created in Moodle will automatically be available in the gem.

Example

Moodle::Api.configure({host: 'http://my_moodle_instance.com', token: 'mytoken'})

params = { 'criteria[0][key]' => 'firstname', 'criteria[0][value]' => 'Jon' }

Moodle::Api.core_user_get_users(params)

Authentication

Moodle uses token authentication, but sometimes you might not have a token. Users are able to generate tokens automatically when calling services using basic authentication.

Moodle::Api.configure({host: 'http://my_moodle_instance.com',
                       service: 'my_external_service', # ensure you include the shortname of the external service
                       username: 'jonsnow',
                       password: 'defendthewall'})

params = { 'criteria[0][key]' => 'firstname', 'criteria[0][value]' => 'Jon' }

Moodle::Api.core_user_get_users(params)

The gem will handle generating the token automatically and making the call to core_user_get_users with the token. If you want you can also just generate a token using

configuration = Moodle::Api::Configuration.new
configuration.host = 'http://example.com'
configuration.username = 'jonsnow'
configuration.password = 'batman'
configuration.service = 'service'
configuration

# Note you could pass in a struct with these attributes and it should work the same
Moodle::Api::TokenGenerator.new(configuration).call

Documentation

• Local documentation - http://[my_moodle_instance].com/admin/webservice/documentation.php
• Service creation guide
• Token creation
• Web Service API function reference
• Testing harness

Development

A bundle install should get you going. Rspec, guard and vcr are leveraged for testing.

Note: regenerating vcr cassettes, some data will change which will break the tests. They are pretty easy to compare and correct with a simple diff. The fields that change are timing fields such as last login date, etc. which are specific to the users system. A todo has been added to make the cassettes easily rerunnable.

Contributing

1. Fork it ( https://github.com/[my-github-username]/moodle-api/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request
6. Ensure your stuff is rubocop'd

I am always keen to learn so please feel free to create an issue with code reviews, suggestions and possible refactorings.

Compatibility

This gem has been used in production against Moodle 2.8 - 3.3. As long as the version you are using has Moodle web services you should be good to go. We are using this gem in production so, future upgrades will be done as releases come out. We will also notify users if we stop maintaining this repo.

TODOS

• Add additional protocols
• Make cassettes easily rerunnable - will require a parser for the response to remove dynamic data or a funky regex in the specs.
• Moodle web services require you to know how the Moodle API expects params. They are pretty messy. It would be nice to leverage hashes and arrays and then parse them to into what moodle expects.