RedcapAPI 0.0.5 → 0.0.6a

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    YWRmMmY4MDRhZmFhZWRkYTJjNGY2NjNmMjQ4Njk2NDUwMWJiNDYyNg==
-  data.tar.gz: !binary |-
-    NWU2OGY2NmExMTM1YjY2ZjgzOTRmYmZjZTM2ZjBkZjg5MWNhYmFjOQ==
+SHA1:
+  metadata.gz: 3ecc5ee19022a7fe8d9bd20f08fb53039a48716b
+  data.tar.gz: 75037075c22cd9bac02d65cbc2e72b0c48ccf742
 SHA512:
-  metadata.gz: !binary |-
-    NGY2MDNlNGUwMmUyZTA5MzczYTM0MWUwZGYxNDhkZDMyNjVjNGU2ZGYxOTBk
-    MDhmYmE2ZmNhNTVmMGM0YmE2M2I0ODYyYjliNmIyYzczZTFmYzRiMDkzOGUy
-    YjU5MmZhOGJmZDQyOGM2ZGFjMTk3ZWU1MzgwZGQxNWQ2YzRhZTg=
-  data.tar.gz: !binary |-
-    YWQ0ODcyNGNiYTI3NmEyMmIwMjAwZGE1YWNiZjkyNWU2YmM5NDllOGZmNjI3
-    NDM2NWM2ODRmY2FjNGU1ZGM4MjY2MDFjNDZiOWE2NjljMTY5YTlmZmRmNDRh
-    N2NlNWJhODJhYjY5YjAwMTAwNWZlMmIzM2IxODFhMTg0NWNlMmE=
+  metadata.gz: 4dabdab78f3a6409c34be703e68496441aed72fe378c7675ee7b05c46c0fed8b81b3da5074de123ecf691cdc8147e2ea2e93aa597d22cb4b278612b6455867fc
+  data.tar.gz: da28bddc0d8b639195a157713f7ac9348b1eb09ba6b3513e77e9a722b22b227ffe234b16cbf76c6a3fd998129e87b32bbc72ad4f4ef8fef2a3b744a4f18872ef

data/README.md

@@ -3,11 +3,66 @@
 This is an api to utilize REDCAP api with ruby. This Gem requires mechanize as a dependency.
 it is based on instructions here http://sburns.org/2013/07/22/intro-to-redcap-api.html
 
+This gem is under development and testing.  If you would like to make changes or have comments, reach me at eugene@tranquiltech.io
+
+Special thanks to mmcrockett for making great additions. 
+  
 To start:
+```ruby
+r = RedcapAPI.new(token, url, parser) 
+```
+your institution has it's own url, and each project has it's own token, an optional 'parser' that defaults to JSON. See the test cases for how to use other parsers like Nokogiri::XML and CSV.
+
+```ruby
+r.export(optional params) 
+```
+returns all records in JSON format, provide additional hash of parameters in you want to override or add any additional RedcapAPI options.
+
+```ruby
+r.export_metadata(optional params) 
+```
+returns all metadata records in JSON format, provide additional hash of parameters in you want to override or add any additional RedcapAPI options.
+
+```
+r.import(optional params)
+```
+imports new records, the 'post' method is likely more helpful as it puts the 'data' in the correct format.
+
+```
+r.api(optional params) 
+```
+returns the raw data, this allows you to return 'xml' or 'csv' instead of forcing 'json'. Simply override the params. Example r.api({:format => 'xml'}).
+```
+r.get(optional record_id) 
+```
+returns all records in JSON format or a specific record if specified
+```
+r.get_fields 
+```
+returns all fields for that instrument
+```
+r.post(data) 
+```
+this will either update an old record or create a new one. the data should be in form of array of hashes or as a hash (for one item).  dates are accepted in Date class or in strftime('%F') format. 
+for example
+```
+  data = {name: 'this is a test', field_2: Date.today}
+  r.post(data)
+```
+creates a new object using the fields above. field names must match those in the existing project
+  "{\"count\": 1}" --> indicates the object posted. 
 
-r = RedcapAPI.new(token, url) # your institution has it's own url, and each project has it's own token
+to update an existing record:
+```
+data = {record_id: 3, name: 'this is a test to update', field_2: Date.today}
+r.post(data) 
+```
+this will update the record with record_id 3. if record_id 3 does not exist it will create an entry with that record id
 
-r.get(optional record_id) # returns all records in JSON format or a specific record if specified
+There is also a helper class added to ruby Hash allowing you to convert a ruby array to a http-post style array. It was created  after having some issues filtering on 'forms' and 'fields'
+Example:
+params = {:fields => ['record_id', 'lab_id'], :forms => ['slide_tracking', 'id_shipping']} # This is the data I want to send to RedcapAPI, limiting the fields and forms
+r.export_metadata(params.to_http_post_array()) # This gets the metadata for only those fields/forms by using the newly added method on Hash 'to_http_post_array'.
 
 ## Contributing
 

data/Rakefile

@@ -1,2 +1,9 @@
 require "bundler/gem_tasks"
+require 'rake/testtask'
 
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+end
+
+desc "Run tests"
+task :default => :test

data/RedcapAPI.gemspec

@@ -9,20 +9,10 @@ Gem::Specification.new do |spec|
   spec.authors       = ["eugyev"]
   spec.email         = ["eugyev@gmail.com"]
   spec.summary       = %q{This is an api to utilize REDCAP api with ruby. This Gem requires mechanize as a dependency.
-  it is based on instructions here http://sburns.org/2013/07/22/intro-to-redcap-api.html
+  The backend is based on instructions here http://sburns.org/2013/07/22/intro-to-redcap-api.html
   }
   spec.description   = %q{
-    This gem is still under active development. Please contact me directly with any  questions or suggestions. 
-    
-  To start:
-
-  r = RedcapAPI.new(token, url) # your institution has it's own url, and each project has it's own token
-
-  r.get(optional record_id) # returns all records in JSON format or a specific record if specified
-  
-  r.get_fields # returns all fields for that instrument
-  
-  r.post(data) # this will either update an old record or create a new one. the data should be in form of array of hashes or as a hash (for one item).  dates are accepted in Date class or in strftime('%F') format. 
+    Please see Github Repo and Readme file https://github.com/eugyev/RedcapAPI
   }
   spec.homepage      = ""
   spec.license       = "MIT"
@@ -34,5 +24,8 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency "bundler", "~> 1.6"
   spec.add_development_dependency "rake"
-  spec.add_development_dependency "mechanize"
+  spec.add_development_dependency "csv"
+  spec.add_development_dependency "nokogiri"
+  spec.add_dependency "mechanize"
+  spec.add_dependency "json"
 end

data/lib/RedcapAPI.rb

@@ -1,13 +1,40 @@
 require "RedcapAPI/version"
+require "json"
+require "mechanize"
+  class Hash
+    def to_http_post_array
+      r = {}
+
+      self.each_key do |k|
+        if (false == self[k].is_a?(Array))
+          raise "!ERROR: Expecting hash value to be an Array."
+        end
+
+        self[k].each_with_index do |v,i|
+          r["#{k}[#{i}]"] = v
+        end
+      end
+
+      return r
+    end
+  end
+
   class RedcapAPI
-    def initialize(token, url)
-      @url = url
-      @token = token
+    DEFAULT_PARAMS = {
+      :content => 'record',
+      :format  => 'json',
+      :type    => 'flat'
+    }
+
+    def initialize(token, url, parser = JSON)
+      @url     = url
+      @payload = DEFAULT_PARAMS
+      @payload[:token] = token
+      @parser  = parser
     end
 
     def get(record_id = nil)
-      payload = {:token=>@token, :format=>"json", :content=>"record", :type => 'flat'}
-      data = JSON.parse Mechanize.new.post(@url, payload).body
+      data = self.export()
       if record_id
         data = data.select{|x| x['record_id'] == record_id.to_s}
       end
@@ -15,8 +42,7 @@ require "RedcapAPI/version"
     end
   
     def get_fields
-      payload = {:token=>@token, :format=>"json", :content=>"metadata"}
-      response = JSON.parse Mechanize.new.post(@url, payload).body
+      response = export_metadata()
       if response
         response.collect {|r| r['field_name'] if r }
       end
@@ -25,8 +51,7 @@ require "RedcapAPI/version"
     def post(data)
       data = filter_data(data)
       data_string = data.to_json
-      payload = {:token => @token, :format=> 'json', :content=>'record', :type => 'flat', :data => data_string}
-      Mechanize.new.post(@url, payload).body      
+      return self.import({:data => data_string})
     end
   
     def filter_data(data)
@@ -56,4 +81,22 @@ require "RedcapAPI/version"
         (max_entry.to_i + 1).to_s
       end
     end
+
+    def export(params = {})
+      return @parser.parse(api(params))
+    end
+
+    def export_metadata(params = {})
+      payload = {:content => 'metadata'}.merge(params)
+      return self.export(payload)
+    end
+
+    def import(params = {})
+      return api(params)
+    end
+
+    def api(params = {})
+      payload = @payload.merge(params)
+      return Mechanize.new.post(@url, payload).body
+    end
   end

data/lib/RedcapAPI/version.rb

@@ -1,3 +1,3 @@
 class RedcapAPI
-  VERSION = "0.0.5"
+  VERSION = "0.0.6a"
 end

data/test/test_redcap_api.rb

@@ -0,0 +1,105 @@
+require 'test/unit'
+require 'RedcapAPI'
+require 'csv'
+require 'Nokogiri'
+
+class Hash
+  def body
+    return self[:body]
+  end
+end
+
+class Mechanize
+  def post(url, payload)
+    v = {}
+
+    if ('json' == payload[:format])
+      if ('metadata' == payload[:content])
+        v[:body] = '[{"field_name":"record_id", "form_name":"form0"},{"field_name":"first_name", "form_name":"form0"},{"field_name":"trc_id", "form_name":"form0"}]'
+      else
+        v[:body] = '[{"record_id":"1", "trc_id":"b", "first_name":"bob"},{"record_id":"2", "trc_id":"c", "first_name":"chris"}]'
+      end
+    elsif ('xml' == payload[:format])
+      v[:body] = '<?xml version="1.0" encoding="UTF-8" ?><records><item><record_id><![CDATA[1]]></record_id><trc_id>b</trc_id><first_name>bob</first_name></item><item><record_id><![CDATA[2]]></record_id><trc_id>c</trc_id><first_name>chris</first_name></item></records>'
+    elsif ('csv' == payload[:format])
+      v[:body] = 'record_id,trc_id,first_name'
+      v[:body] << "\n"
+      v[:body] << '"1","b","bob"'
+      v[:body] << "\n"
+      v[:body] << '"2","c","chris"'
+    else
+      raise "!ERROR: unkown format '#{payload[:format]}'."
+    end
+
+    return v
+  end
+end
+
+class RedcapAPITest < Test::Unit::TestCase
+  def test_hash_extension
+    t = {:a => [1,2,3], :b => ["h", "i", "j"]}
+    e = {"a[0]" => 1, "a[1]" => 2, "a[2]" => 3, "b[0]" => "h", "b[1]" => "i", "b[2]" => "j"}
+    assert_equal(e, t.to_http_post_array)
+  end
+
+  def test_default_parser
+    default   = RedcapAPI.new("", "").export()
+    json_data = RedcapAPI.new("", "", JSON).export({:format => 'json'})
+
+    assert_equal(json_data, default)
+  end
+
+  def test_xml_parser
+    xml_data  = RedcapAPI.new("", "", Nokogiri::XML::Document).export({:format => 'xml'})
+    json_data = RedcapAPI.new("", "", JSON).export({:format => 'json'})
+    xml_to_json_data = []
+
+    xml_data.xpath(".//item").each do |item_node|
+      json_record = {}
+      item_node.children().each do |value_node|
+        json_record[value_node.name()] = value_node.content()
+      end
+      xml_to_json_data << json_record
+    end
+
+    assert_equal(json_data, xml_to_json_data)
+  end
+
+  def test_csv_parser
+    csv_data  = RedcapAPI.new("", "", CSV).export({:format => 'csv'})
+    json_data = RedcapAPI.new("", "", JSON).export({:format => 'json'})
+    csv_to_json_data = []
+
+    csv_data.each_with_index do |record,i|
+      if (0 != i)
+        json_record = {}
+        record.each_with_index do |value,j|
+          json_record[csv_data[0][j]] = value
+        end
+        csv_to_json_data << json_record
+      end
+    end
+
+    assert_equal(json_data, csv_to_json_data)
+  end
+
+  def test_param_override
+    metadata = RedcapAPI.new("", "").export_metadata()
+    data     = RedcapAPI.new("", "").export_metadata({:content => 'record'})
+
+    assert_not_equal(data, metadata)
+  end
+
+  def test_metadata
+    metadata = RedcapAPI.new("", "").export_metadata()
+    data = [{"field_name"=>"record_id", "form_name"=>"form0"},{"field_name"=>"first_name", "form_name"=>"form0"},{"field_name"=>"trc_id", "form_name"=>"form0"}]
+
+    assert_equal(data, metadata)
+  end
+
+  def test_get_fields
+    fields = RedcapAPI.new("", "").get_fields()
+
+    assert_equal(["record_id", "first_name", "trc_id"], fields)
+  end
+end

metadata

@@ -1,72 +1,108 @@
 --- !ruby/object:Gem::Specification
 name: RedcapAPI
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6a
 platform: ruby
 authors:
 - eugyev
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-07-13 00:00:00.000000000 Z
+date: 2015-06-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.6'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.6'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: mechanize
+  name: csv
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ! '>='
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: mechanize
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: ! "\n    This gem is still under active development. Please contact me
-  directly with any  questions or suggestions. \n    \n  To start:\n\n  r = RedcapAPI.new(token,
-  url) # your institution has it's own url, and each project has it's own token\n\n
-  \ r.get(optional record_id) # returns all records in JSON format or a specific record
-  if specified\n  \n  r.get_fields # returns all fields for that instrument\n  \n
-  \ r.post(data) # this will either update an old record or create a new one. the
-  data should be in form of array of hashes or as a hash (for one item).  dates are
-  accepted in Date class or in strftime('%F') format. \n  "
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: "\n    Please see Github Repo and Readme file https://github.com/eugyev/RedcapAPI\n
+  \ "
 email:
 - eugyev@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
+- ".gitignore"
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -74,6 +110,7 @@ files:
 - RedcapAPI.gemspec
 - lib/RedcapAPI.rb
 - lib/RedcapAPI/version.rb
+- test/test_redcap_api.rb
 homepage: ''
 licenses:
 - MIT
@@ -84,19 +121,20 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ! '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ! '>='
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
 summary: This is an api to utilize REDCAP api with ruby. This Gem requires mechanize
-  as a dependency. it is based on instructions here http://sburns.org/2013/07/22/intro-to-redcap-api.html
-test_files: []
+  as a dependency. The backend is based on instructions here http://sburns.org/2013/07/22/intro-to-redcap-api.html
+test_files:
+- test/test_redcap_api.rb