Skip to content
A ruby client for Patient Study Calendar's RESTful API
Ruby Shell
Find file
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
features
int-psc
lib
spec
tasks
.gitignore
.rvmrc
.yardopts
CHANGELOG.md
Gemfile
LICENSE
README-ssl.md
README.md
Rakefile
ci-exec.sh
cucumber.yml
psc.gemspec

README.md

psc.rb

psc.rb is a ruby client for Patient Study Calendar's RESTful HTTP API. It provides assistance with authentication to PSC's API and with executing common tasks. It also provides a lower-level interface (Psc::Connection) to allow for making HTTP requests against the configured PSC's API directly.

By design, the client provides a very thin abstraction over the API itself. Please be familiar with the API (whose documentation is available in your PSC instance at api/v1/docs or on the demo site) before using this library.

Overview

require 'psc'
require 'pp'

psc = Psc::Client.new(
  'https://demos.nubic.northwestern.edu/psc',
  :authenticator => { :basic => ['superuser', 'superuser'] }
)

pp psc.studies

(This code will run if you have the psc gem installed, so long as your ruby's openssl has a reasonable set of commercial CAs configured; try it and see. If you get a certificate validation error, check out {file:README-ssl.md} for some tips.)

Note that this overview uses the high-level Psc::Client interface. It does not provide a complete interface to PSC; for most of PSC's API, you'll need to use the lower-level Psc::Connection interface; see below.

Installing

psc.rb is available as a rubygem:

$ gem install psc

Authentication

PSC supports two forms of authentication for API calls: HTTP Basic (i.e., username & password) and psc_token. (Which forms are supported in your PSC instance will depend on its authentication system configuration.)

A particular client instance will only use one authentication mechanism. There are three options.

HTTP Basic

PSC Client allows you to specify a username and password to use for all requests. Include the :authenticator key like so:

:authenticator => { :basic => %w(alice password) }

=> Authorization: Basic YWxpY2U6cGFzc3dvcmQ=

Static token

Alternatively, you can provide a token to use in all requests:

:authenticator => { :token => 'The raven flies at midnight' }

=> Authorization: psc_token The raven flies at midnight

Dynamic token

Finally, you can provide a callable object which will be invoked for each request and whose return value will be used for the PSC token:

:authenticator => { :token => lambda { cas_client.get_proxy_ticket } }

=> Authorization: psc_token PT-133-236H522

The callable will be called with no arguments.

High-level interface

{Psc::Client} provides a high-level interface to some of PSC's API capabilities.

Low-level interface

psc.rb is based on Faraday, a modular ruby HTTP client. {Psc::Connection} is a Faraday connection configured for access to a particular PSC instance. You can create a Psc::Connection directly:

conn = Psc::Connection.new(
  'https://demos.nubic.northwestern.edu/psc',
  :authenticator => { :basic => %w(superuser superuser) })

Or you can get an instance from the {Psc::Client} high-level interface:

client = Psc::Client.new(
  'https://demos.nubic.northwestern.edu/psc',
  :authenticator => { :basic => %w(superuser superuser) })
conn = client.connection

The connection is set up to automatically parse JSON reponses into appropriate ruby primitives and XML responses into Nokogiri documents.

studies_json = conn.get('studies.json')
first_study_name =
  studies_json.body['studies'].first['assigned_identifier']

sites_xml = conn.get('sites.xml')
first_site_name =
  sites_xml.body.xpath('//psc:site', Psc.xml_namespace).first.attr('site-name')

Similarly, for PUT and POST it will encode a Hash or Array entity as JSON and will assume that a String entity is XML.

URLs

PSC's API resources all start with api/v1. To help you DRY things up, PSC::Connection automatically adds this to the base URL on construction. You don't need to include it when constructing relative URLs.

Middleware

Faraday connections are built up from middleware. Psc::Connection uses a combination of off-the-shelf and custom middleware classes. The custom classes are in the {Psc::Faraday} module.

Project info

Running the tests

psc.rb has an rspec suite for unit tests and a set of cucumber features for integration tests. Before you can run the cucumber features you will need to either

  • Execute rake int-psc:war to download a copy of PSC to use
  • Copy a PSC war into int-psc/bin

Patches

Patches with tests are happily considered. Please use a pull request.

Something went wrong with that request. Please try again.