collectiveaccess

= collectiveaccess

This gem is a simple plain Ruby wrapper for the {CollectiveAccess}[http://www.collectiveaccess.org/] Web {Service API}[docs.collectiveaccess.org/wiki/Web_Service_API]. Before you start fiddling with the gem, make sure you're familiar with the API.

Note that this library requires CollectiveAccess Providence v1.5 or later! It might work with v1.4 but we don't test it against the old stable code.

== Setup

Through RubyGems:

gem install collectiveaccess

In a Gemfile:

gem 'collectiveaccess', '~> 0.2.0'

== Usage

The API consists of only class methods. We never save any state except for user credentials.

=== Authentication

You can pass the authentication credentials for your CollectiveAccess setup via environment variables, like so

$ export CA_SERVICE_API_USER='administrator'
$ export CA_SERVICE_API_KEY='dublincore'
$ irb
2.2.1 :001 > require 'collectiveaccess'
 => true
2.2.1 :002 > CollectiveAccess.get

In a Ruby on Rails app you could use the {dotenv}[https://github.com/bkeepers/dotenv] gem to accomplish the same. You can also set the credentials explicitly in your code:

$ irb
2.2.1 :001 > require 'collectiveaccess'
 => true
2.2.1 :002 > CollectiveAccess.set_credentials 'administrator', 'dublincore'
 => {:username=>"administrator", :password=>"dublincore"}
2.2.1 :003 > CollectiveAccess.get

The gem uses these credentials to authenticate with the {login service endpoint}[http://docs.collectiveaccess.org/wiki/Web_Service_API#Authentication] and obtain an authentication service token. It then saves this token, which is valid for about an hour by default, in a temporary file in the local file system so that it can restore the session on subsequent requests.

=== Queries

The CollectiveAccess class has static methods for all the HTTP request schemes the service API uses: get, post, put, delete, options. All these methods take a single options hash as parameter. Below is the default hash that gets merged with whatever you pass. All these keys are available.

DEFAULT_REQUEST_OPTS = {
    protocol: 'http',
    hostname: 'localhost',
    url_root: '/',
    script_name: 'service.php',
    table_name: 'ca_objects',
    endpoint: 'item',
    request_body: {},
    get_params: {},
    url_string: ''
}

The methods return the parsed JSON response from the API as hash, or nil of something went wrong. Below are a few examples. All of them assume that you have required the 'collectiveaccess' gem and also that authentication is set up correctly (see above).

===== Get a generic summary for object with id 1 r = CollectiveAccess.get hostname: 'providence.dev', table_name: 'ca_objects', endpoint: 'item', url_string: '/id/1' puts "#{r}"

===== Get a specific bundle list for object with id 1 r = CollectiveAccess.get hostname: 'providence.dev', table_name: 'ca_objects', endpoint: 'item', url_string: '/id/1', request_body: { bundles: { 'ca_objects.idno' => {}, 'ca_objects.preferred_labels' => {}, 'ca_entities' => { :returnAsArray => true } } } puts "#{r}"

===== Search for * r = CollectiveAccess.get hostname: 'providence.dev', table_name: 'ca_objects', endpoint: 'find', get_params: { q: '*' } puts "#{r}"

===== Search for something more specific, and also specify what we want returned in the result r = CollectiveAccess.get hostname: 'providence.dev', table_name: 'ca_objects', endpoint: 'find', get_params: { q: 'Homer' }, request_body: { bundles: { 'ca_objects.idno' => {}, 'ca_objects.preferred_labels' => {}, 'ca_entities' => { :returnAsArray => true } } } puts "#{r}"

=== "Simple" API

In v1.6 of CollectiveAccess there's a new service interface called {Simple API}[http://docs.collectiveaccess.org/wiki/SimpleAPI]. Gem versions v0.2.x and later support querying this API using the simple class method. Below is an example for the endpoint 'testDetail'. Note that you have to define the endpoint first in your CollectiveAccess services configuration for this to work. For more info take a look at the {documentation}[http://docs.collectiveaccess.org/wiki/SimpleAPI]:

r = CollectiveAccess.simple hostname: 'providence.dev', endpoint: 'testDetail', get_params: { id: 1 }

== Contributing to collectiveaccess

• Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
• Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
• Fork the project.
• Start a feature/bugfix branch.
• Commit and push until you are happy with your contribution.
• Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
• Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

== Copyright

Copyright (c) 2015 Whirl-i-Gig. See LICENSE.txt for further details.