Moodle API

A ruby wrapper for the Moodle REST API.

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/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

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

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.

Warning

This gem is still under heavy development.