Limeade

Ruby interface to the LimeSurvey RemoteControl 2 API

LimeSurvey provides an API for accessing and managing surveys. The current version is RemoteControl 2. It is exposed as a XML-RPC/JSON-RPC based web service. This gem accesses using JSON-RPC.

The goal of this gem is to access the API in a manner that is natural to rubyists. The API is defined in terms of methods and arguments. That's easy to mimic in Ruby by means of #method_missing. Thus, call any of the API's methods on the Limeade client itself!

This gem handles the API session transparently so you don't have to even think about it.

Note that before using the LimeSurvey RemoteControl API you need to activate it for your account. See the manual for instructions on how to do this. Be sure to choose the JSON-RPC option.

Note also that you must activate a survey in order for it to be visible via the API.

Installation

Add this line to your application's Gemfile:

gem 'limeade'

And then execute:

$ bundle

Or install it yourself as:

$ gem install limeade

Usage

Start by requiring limeade into your code.

require 'limeade'

Instantiate a client and start invoking API methods on it. The API methods are documented here. Do not specify the $sSessionKey, as it is added as the first argument automatically. (Recall that the session is managed for you transparently.)

client = Limeade::Client.new(api_uri, username, password)
surveys = client.list_surveys
summary = client.get_summary(surveys.first['sid'])

You'll probably want to get api_uri, username, and password from environment variables.

The responses from the API are parsed from JSON into Ruby objects. Bear in mind that Hash keys are going to be String.

When you are done accessing the API, it is polite to disconnect.

client.disconnect

Retry Mechanism

Not every network call goes as planned. Limeade uses the underlying Faraday gem for handling the transport. Faraday has a retry mechanism, Faraday::Request::Retry. Its behavior is configurable via options offering a high degree of control. These same options may be passed when instantiating Limeade::Client.

client = Limeade::Client.new(api_uri, username, password, max: 5, interval: 1.5)

View the Limeade::Client documentation for details.

Logging

The gem defines a logger for its own use. Access it via Limeade.logger. Change logging level like so Limeade.logger.level = Logger::WARN

You can substitute your own logger to consolidate logging throughout your app:

Limeade.logger = my_apps_logger

Development

After checking out the repo, run bin/setup to install dependencies.

The specs rely on API location and credentials being defined as environment variables. Edit bin/env.sh for your situation, then execute it.

$ source bin/env.sh

Then run the tests.

$ bundle exec rake spec

You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/spokesoftware/limeade. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.
Copyright 2019 David Pellegrini and Spoke Software, Inc.

Code of Conduct

Everyone interacting in the Limeade project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.