Symgate - Ruby client for the Widgit symbolisation service

This gem provides a wrapper around the Symgate SOAP API, providing a simple Ruby interface that matches the remote API as much as possible.

The API provides a client for each of the sections of API functionality. These are:

Symgate::Auth::Client for authentication, user and group management
Symgate::Wordlist::Client for per-user/group metadata storage
Symgate::Metadata::Client for per-user/group wordlist management

Please note that a symbolisation client is scheduled for a future release.

Prerequisites

This gem works with Ruby 2.1 and above

Installation

Add this line to your application's Gemfile:

gem 'symgate'

And then execute:

$ bundle

Or install it yourself as:

$ gem install symgate

Usage

Initialisation

To call any Symgate methods you must create a client of the relevant type. These can be instantiated in the following ways:

Account/key

require 'symgate/auth'

auth_client = Symgate::Auth::Client.new(account: 'my_account', key: 'secret')

User/password

require 'symgate/wordlist'

wordlist_client = Symgate::Wordlist::Client.new(account: 'my_account', 
                                                user: 'group/user',
                                                password: 'secret')

User/token

You need to call the authenticate method in order to obtain a token:

require 'symgate/auth'
require 'symgate/metadata'

# obtain a token from the authentication client

auth_client = Symgate::Auth::Client.new(account: 'my_account', 
                                        user: 'group/user',
                                        password: 'secret')

begin
  token = auth_client.authenticate
rescue Symgate::Error => e
  puts "Authentication failed with the following error: #{e.message}"
end

metadata_client = Symgate::Metadata::Client.new(account: 'my_account',
                                                user: 'group/user',
                                                token: token)

Other initialisation options

You can also initialise a client with the following options:

Option
:endpoint	Specifies the symbolisation SOAP endpoint to use, if not the public symbolisation server.
:savon_opts	Specifies options to pass to the underlying savon engine. e.g. `{ log_level: :debug }`
:data_required_error_retries	Specifies the number of times to attempt a request when the response is 'Data required for operation'.

Errors

If any method call fails, it will raise a Symgate::Error exception. Examine the exception for further information on what went wrong.

Further documentation

For more information, see the documentation at:

http://www.rubydoc.info/github/symbols-worldwide/symgate-gem/

Development

After checking out the repository, run bundle install to obtain the necessary development gems.

Run rake test to run the tests, which consist of

rubocop
rspec (with coverage)

Successful PRs require 100% code coverage and all tests and cops passing.

Integration tests

If you want to run the integration tests (test the gem against a running server):

Install Vagrant 1.8 or later, if not already installed
Run rake vagrant:up to set up a local VM running the latest symboliser.
Run rake spec:integration to run the integration tests.

To pause testing until later, run rake vagrant:halt which will suspend your virtual machine. To resume testing run rake vagrant:up again.

To shut down and destroy the VM completely, run rake vagrant:destroy

Note that you need access to the Widgit CI server for this to work.

Alternatively, in the highly unlikely event that the Vagrant stuff doesn't work, you can run the tests against some other running symboliser by copying test/config/local.example.yml to test/config/local.yml and editing local.yml to include the particulars of your symboliser endpoint, database and WSDL.

License

This project is licensed under the Apache License 2.0.

Contributing

Fork it ( https://github.com/symbols-worldwide/symgate-gem/fork )
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create a new Pull Request