roqua-rom-api 0.0.9 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9e4c9540bc5e468f4b51c4cfab6016fbcea74241
-  data.tar.gz: 1404eaf705529199115775862aa7fe202fe80d16
+  metadata.gz: 475ac6de577ac65fdf2e2da65ec85adf70dbbfaf
+  data.tar.gz: 31f5cb17b157a41080c1b9bf547a263c804a1e99
 SHA512:
-  metadata.gz: afcb437a07656bc8035000c59412f0799456b25f898409a976e1d8cd63f3676deca20919ecd9eea4501747223f585a60acd621e80500544238dca2be60847988
-  data.tar.gz: 288b8f042d92285cce3cbd16c793fb0cdd233d789ad3178794a8bb765086a068bdea06f24c96504fc71ff495627ef28bc12b8c5bae3d597495bce35df33fe9bd
+  metadata.gz: 6a1cc7174e50cb2efd8166ea1b0494576c4e13b826dac3a4445434bace1f8f596022d2e032c636814cf33966ddbd9dc80d6960324b40d49f14418a5bc67f4765
+  data.tar.gz: 7abe459bd3921fc2a6f757d841080aee2da6c557bf047c9ada203f000b8866b5a6a471cbb994786bddfc29b826ce5b8354e834010c4d31691b1bde41d6de0077

data/ChangeLog.md

@@ -1,3 +1,11 @@
+### 0.1.1 / 2014-0-23
+
+* Validate api responses
+* From now on the Responses API is accessible through the Responses interactor. The received responses can be obtained through the `#responses` accessor when the interactor outcome is valid.
+* Similarly the the ProtocolSubscriptions API is hence forth accessible through the ProtocolSubscriptions interactor. The received protocol subscriptions can be obtained through the `#protocol_subscriptions` accessor when the interactor outcome is valid.
+* Add accessor for fill_out_session api questionnaire_url
+* Update documentation in README
+
 ### 0.0.9 / 2014-04-14
 
 * Added Virtus to the gemspec

data/README.md

@@ -2,26 +2,125 @@
 
 Make sure the following environment variables are defined:
 
-    ENV['ROM_HOST']    # uri of the RoQua application whose API you are targeting
+    ENV['ROM_HOST']    # URI of the RoQua application whose API you are targeting
     ENV['ROM_KEY']     # username used for HTTP basic authentication on the RoQua API
     ENV['ROM_SECRET']  # password used for HTTP basic authentication on the RoQua API
 
 An HTTP basic auth username password combination can be generated in the RoQua admin interface integration tab
 
+## FillOut Sessions
+
+To start filling out a questionnaire run:
+
+    outcome = Roqua::RomApi::StartFillOutSession.run dossier_id: dossier_id,
+                                                     questionnaire_key: questionnaire_key,
+                                                     return_to: '/some/return/url/or/path'
+
+#### Parameters
+
+ * `dossier_id:`        [Required]           - Unique dossier identifier for the patient about to fill out a questionnaire.
+ * `questionnaire_key:` [Required]           - Key uniquely identifying the questionnaire to be filled out.
+ * `return_to:`         [Required]           - Address to return to after filling out the questionnaire.
+
+Redirect to the questionnaire url received when the outcome is valid:
+
+    if outcome.valid?
+      redirect_to outcome.questionnaire_url
+
+or do something with the validation errors:
+
+    else
+      log_or_display outcome.errors.full_messages
+    end
+
 ## Protocol Subscriptions
 
+### Index
+To retrieve active protocol subscriptions run:
+
+    outcome = Roqua::RomApi::ProtocolSubscription.run dossier_id: dossier_id
+
+#### Parameters
+
+ * `dossier_id:`   [Required]                - Unique dossier identifier for the patient you want the subscriptions for.
+
+When the request succeeds, the subscriptions can be accessed through `#protocol_subscriptions`:
+
+    if outcome.valid?
+      subscriptions = outcome.protocol_subscriptions
+
+Else some validation errors can be shown:
+
+    else
+      log_or_display outcome.errors.full_messages
+    end
+
+### Create
 To subscribe to a protocol run the following command:
 
-    Roqua::RomApi::StartProtocolSubscription.run dossier_id: dossier_id,
-                                                 protocol_key: protocol_key,
-                                                 start_at: start_at
+    outcome = Roqua::RomApi::StartProtocolSubscription.run dossier_id: dossier_id,
+                                                           protocol_key: protocol_key,
+                                                           start_at: start_at
 
-#### Subscription options
+#### Parameters
 
- * `dossier_id:`   [Required]                - Unique identifier for the patient to be subscribed.
+ * `dossier_id:`   [Required]                - Unique dossier identifier for the patient to be subscribed.
  * `protocol_key:` [Required]                - Key uniquely identifying the protocol of interest as specified in RoQua.
  * `start_at:`     [Defaults to the present] - Timestamp specifying when the first measurement should be prepared.
 
+When the subscription succeeds, the subscription object is available through the `#result` accessor:
+
+    if outcome.valid?
+      subscription = outcome.result
+
+Else the validation errors can be inspected:
+
+    else
+      log_or_display outcome.errors.full_messages
+    end
+
+### Destroy
+To unsubscribe from a protocol run the command:
+
+    outcome = Roqua::RomApi::StopProtocolSubscription.run dossier_id: dossier_id,
+                                                          protocol_subscription_id: subscription_id
+
+#### Parameters
+
+  * `dossier_id:`               [Required]   - Unique dossier identifier for the patient to be unsubscribed.
+  * `protocol_subscription_id:` [Required]   - Unique identifier for the protocolsubscription to be stopped.
+
+When stopping the subscription succeeds, the subscription object is available through the `#result` accessor:
+
+    if outcome.valid?
+      subscription = outcome.result
+
+Else the validation errors can be inspected:
+
+    else
+      log_or_display outcome.errors.full_messages
+    end
+
+## Responses
+
+To retrieve filled out, pending or scheduled questionnaires run:
+
+    outcome = Roqua::RomApi::Responses.run dossier_id: dossier_id
+
+#### Parameters
+
+ * `dossier_id:`   [Required]                - Unique dossier identifier for the patient you want the responses for.
+
+When the request succeeds, the responses can be accessed through `#responses`:
+
+    if outcome.valid?
+      responses = outcome.responses
+
+Else some validation errors can be shown:
+
+    else
+      log_or_display outcome.errors.full_messages
+    end
 
 ## Contributing to roqua-rom-api
 

data/lib/roqua/rom_api/endpoint.rb

@@ -0,0 +1,18 @@
+module Roqua
+  module RomApi
+    # @api private
+    class Endpoint < ActiveInteraction::Base
+      private
+
+      def validate_response_for
+        response = yield
+        if response && response['errors']
+          response['errors'].each do |error|
+            errors.add :base, error
+          end
+        end
+        response
+      end
+    end
+  end
+end

data/lib/roqua/rom_api/protocol_subscriptions.rb

@@ -0,0 +1,18 @@
+module Roqua
+  module RomApi
+    # @api private
+    class ProtocolSubscriptions < Endpoint
+      string :dossier_id
+
+      def execute
+        validate_response_for do
+          RomApi.basic_auth_session.get "/dossiers/#{dossier_id}/protocol_subscriptions"
+        end
+      end
+
+      def protocol_subscriptions
+        result['protocol_subscriptions'].map { |s| Models::ProtocolSubscription.new(s) }
+      end
+    end
+  end
+end

data/lib/roqua/rom_api/responses.rb

@@ -0,0 +1,18 @@
+module Roqua
+  module RomApi
+    # @api private
+    class Responses < Endpoint
+      string :dossier_id
+
+      def execute
+        validate_response_for do
+          RomApi.basic_auth_session.get "/dossiers/#{dossier_id}/responses"
+        end
+      end
+
+      def responses
+        result['responses'].map { |r| Models::Response.new(r) }
+      end
+    end
+  end
+end

data/lib/roqua/rom_api/start_fill_out_session.rb

@@ -1,15 +1,21 @@
 module Roqua
   module RomApi
     # @api private
-    class StartFillOutSession < ActiveInteraction::Base
+    class StartFillOutSession < Endpoint
       string :dossier_id
       string :questionnaire_key
       string :return_to
 
       def execute
-        RomApi.basic_auth_session.post("/dossiers/#{dossier_id}/fill_out_sessions",
-                                       questionnaire_key: questionnaire_key,
-                                       return_to: return_to).parsed_response
+        validate_response_for do
+          RomApi.basic_auth_session.post("/dossiers/#{dossier_id}/fill_out_sessions",
+                                         questionnaire_key: questionnaire_key,
+                                         return_to: return_to)
+        end
+      end
+
+      def questionnaire_url
+        result['questionnaire_url']
       end
     end
   end

data/lib/roqua/rom_api/start_protocol_subscription.rb

@@ -1,7 +1,7 @@
 module Roqua
   module RomApi
     # @api private
-    class StartProtocolSubscription < ActiveInteraction::Base
+    class StartProtocolSubscription < Endpoint
       string :dossier_id
       string :protocol_key
       time :start_at, default: nil
@@ -9,7 +9,9 @@ module Roqua
       def execute
         options = {protocol_key: protocol_key}
         options[:start_at] = start_at.to_i if start_at
-        RomApi.basic_auth_session.post("/dossiers/#{dossier_id}/protocol_subscriptions", options).parsed_response
+        validate_response_for do
+          RomApi.basic_auth_session.post("/dossiers/#{dossier_id}/protocol_subscriptions", options)
+        end
       end
     end
   end

data/lib/roqua/rom_api/stop_protocol_subscription.rb

@@ -1,13 +1,14 @@
 module Roqua
   module RomApi
     # @api private
-    class StopProtocolSubscription < ActiveInteraction::Base
+    class StopProtocolSubscription < Endpoint
       string :dossier_id
       string :protocol_subscription_id
 
       def execute
-        url = "/dossiers/#{dossier_id}/protocol_subscriptions/#{protocol_subscription_id}"
-        RomApi.basic_auth_session.delete(url).parsed_response
+        validate_response_for do
+          RomApi.basic_auth_session.delete("/dossiers/#{dossier_id}/protocol_subscriptions/#{protocol_subscription_id}")
+        end
       end
     end
   end

data/lib/roqua/rom_api/version.rb

@@ -1,5 +1,5 @@
 module Roqua
   module RomApi
-    VERSION = '0.0.9'
+    VERSION = '0.1.1'
   end
 end

data/lib/roqua/rom_api.rb

@@ -2,11 +2,12 @@ require 'active_interaction'
 require 'roqua/rom_api/version'
 require 'roqua/rom_api/sessions'
 require 'roqua/rom_api/models'
+require 'roqua/rom_api/endpoint'
+require 'roqua/rom_api/protocol_subscriptions'
+require 'roqua/rom_api/responses'
+require 'roqua/rom_api/start_fill_out_session'
 require 'roqua/rom_api/start_protocol_subscription'
 require 'roqua/rom_api/stop_protocol_subscription'
-require 'roqua/rom_api/start_fill_out_session'
-require 'roqua/rom_api/list_responses'
-require 'roqua/rom_api/list_protocol_subscriptions'
 
 module Roqua
   module RomApi

data/spec/lib/roqua/rom_api/endpoint_spec.rb

@@ -0,0 +1,37 @@
+require 'spec_helper'
+
+describe Endpoint do
+  class TestEndpoint < Endpoint
+    hash :response, strip: false
+
+    def execute
+      validate_response_for do
+        response.stringify_keys
+      end
+    end
+  end
+
+  describe 'with validations' do
+    it 'returns the response' do
+      outcome = TestEndpoint.run response: {'some' => ['values']}
+      expect(outcome.result).to eq('some' => ['values'])
+    end
+
+    it 'is valid' do
+      result = TestEndpoint.run response: {'some' => ['values']}
+      expect(result).to be_valid
+    end
+
+    context 'when the response contains errors' do
+      it 'adds the errors' do
+        result = TestEndpoint.run response: {'errors' => ['Some annoying error.']}
+        expect(result.errors.full_messages).to include('Some annoying error.')
+      end
+
+      it 'marks the result as invalid' do
+        result = TestEndpoint.run response: {'errors' => ['Some annoying error.']}
+        expect(result).not_to be_valid
+      end
+    end
+  end
+end

data/spec/lib/roqua/rom_api/{list_protocol_subscriptions_spec.rb → protocol_subscriptions_spec.rb}

@@ -1,6 +1,6 @@
 require 'spec_helper'
 
-describe ListProtocolSubscriptions do
+describe ProtocolSubscriptions do
   let(:options)  { {dossier_id: '1'} }
   let(:api_path) { "/dossiers/#{options[:dossier_id]}/protocol_subscriptions" }
   let(:response) { {"protocol_subscriptions" => [{"id" => 1}]} }
@@ -9,10 +9,10 @@ describe ListProtocolSubscriptions do
 
   it 'returns an array of response objects' do
     allow(session).to receive(:get).with(api_path).and_return response
-    result = ListProtocolSubscriptions.run(options).result
+    protocol_subscriptions = ProtocolSubscriptions.run(options).protocol_subscriptions
 
-    expect(result).to be_a(Array)
-    expect(result.first).to be_a(ProtocolSubscription)
-    expect(result.first.id).to eq(1)
+    expect(protocol_subscriptions).to be_a(Array)
+    expect(protocol_subscriptions.first).to be_a(ProtocolSubscription)
+    expect(protocol_subscriptions.first.id).to eq(1)
   end
 end

data/spec/lib/roqua/rom_api/{list_responses_spec.rb → responses_spec.rb}

@@ -1,6 +1,6 @@
 require 'spec_helper'
 
-describe ListResponses do
+describe Responses do
   let(:options)  { {dossier_id: '1'} }
   let(:api_path) { "/dossiers/#{options[:dossier_id]}/responses" }
   let(:response) { {"responses" => [{"name" => "response_1"}, {"name" => "response_2"}]} }
@@ -9,10 +9,10 @@ describe ListResponses do
 
   it 'returns an array of response objects' do
     allow(session).to receive(:get).with(api_path).and_return response
-    result = ListResponses.run(options).result
+    responses = Responses.run(options).responses
 
-    expect(result).to be_a(Array)
-    expect(result.first).to be_a(Response)
-    expect(result.first.name).to eq('response_1')
+    expect(responses).to be_a(Array)
+    expect(responses.first).to be_a(Response)
+    expect(responses.first.name).to eq('response_1')
   end
 end

data/spec/lib/roqua/rom_api/start_fill_out_session_spec.rb

@@ -3,8 +3,7 @@ require 'spec_helper'
 describe StartFillOutSession do
   let(:options) { {dossier_id: 'some_dossier_id', questionnaire_key: 'some_key', return_to: '/some/return/url'} }
   let(:session) { Sessions::BasicAuthSession.new }
-  let(:parsed_response) { double('parsed_response') }
-  let(:response) { double('response', parsed_response: parsed_response) }
+  let(:response) { double('response', :[] => nil) }
   before do
     allow(Sessions::BasicAuthSession).to receive(:new).and_return session
     allow(session).to receive(:post).and_return response
@@ -17,7 +16,13 @@ describe StartFillOutSession do
     StartFillOutSession.run!(options)
   end
 
-  it 'returns the parsed response' do
-    expect(StartFillOutSession.run!(options)).to eq(parsed_response)
+  it 'returns the response' do
+    expect(StartFillOutSession.run!(options)).to eq(response)
   end
-end
+
+  it 'gives access to the received questionnaire url' do
+    allow(session).to receive(:post).and_return 'questionnaire_url' => 'some_questionnaire_url'
+    outcome = StartFillOutSession.run(options)
+    expect(outcome.questionnaire_url).to eq('some_questionnaire_url')
+  end
+end

data/spec/lib/roqua/rom_api/start_protocol_subscription_spec.rb

@@ -3,8 +3,7 @@ require 'spec_helper'
 describe StartProtocolSubscription do
   let(:options) { {dossier_id: 'some_dossier_id', protocol_key: 'some_key'} }
   let(:session) { Sessions::BasicAuthSession.new }
-  let(:parsed_response) { double('parsed_response') }
-  let(:response) { double('response', parsed_response: parsed_response) }
+  let(:response) { double('response', :[] => nil) }
   before do
     allow(Sessions::BasicAuthSession).to receive(:new).and_return session
     allow(session).to receive(:post).and_return response
@@ -24,7 +23,7 @@ describe StartProtocolSubscription do
     StartProtocolSubscription.run!(options.merge start_at: start_at)
   end
 
-  it 'returns the parsed response' do
-    expect(StartProtocolSubscription.run!(options)).to eq(parsed_response)
+  it 'returns the response' do
+    expect(StartProtocolSubscription.run!(options)).to eq(response)
   end
 end

data/spec/lib/roqua/rom_api/stop_protocol_subscription_spec.rb

@@ -2,8 +2,7 @@ require 'spec_helper'
 
 describe StopProtocolSubscription do
   let(:options)  { {dossier_id: 'some_dossier_id', protocol_subscription_id: 'some_protsub_id'} }
-  let(:parsed_response) { double('parsed_response') }
-  let(:response) { double('response', parsed_response: parsed_response) }
+  let(:response) { double('response', :[] => nil) }
 
   let(:session) { Fabricate :basic_auth_session }
   before do
@@ -16,4 +15,8 @@ describe StopProtocolSubscription do
     expect(session).to receive(:delete).with(url)
     StopProtocolSubscription.run!(options)
   end
+
+  it 'returns the response' do
+    expect(StopProtocolSubscription.run!(options)).to eq(response)
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: roqua-rom-api
 version: !ruby/object:Gem::Version
-  version: 0.0.9
+  version: 0.1.1
 platform: ruby
 authors:
 - Samuel Esposito
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-04-16 00:00:00.000000000 Z
+date: 2014-04-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -138,11 +138,12 @@ files:
 - Rakefile
 - lib/roqua-rom-api.rb
 - lib/roqua/rom_api.rb
-- lib/roqua/rom_api/list_protocol_subscriptions.rb
-- lib/roqua/rom_api/list_responses.rb
+- lib/roqua/rom_api/endpoint.rb
 - lib/roqua/rom_api/models.rb
 - lib/roqua/rom_api/models/protocol_subscription.rb
 - lib/roqua/rom_api/models/response.rb
+- lib/roqua/rom_api/protocol_subscriptions.rb
+- lib/roqua/rom_api/responses.rb
 - lib/roqua/rom_api/sessions.rb
 - lib/roqua/rom_api/sessions/basic_auth_session.rb
 - lib/roqua/rom_api/start_fill_out_session.rb
@@ -151,10 +152,11 @@ files:
 - lib/roqua/rom_api/version.rb
 - roqua_rom_api.gemspec
 - spec/fabricators/basic_auth_session_fabricator.rb
-- spec/lib/roqua/rom_api/list_protocol_subscriptions_spec.rb
-- spec/lib/roqua/rom_api/list_responses_spec.rb
+- spec/lib/roqua/rom_api/endpoint_spec.rb
 - spec/lib/roqua/rom_api/models/protocol_subscription_spec.rb
 - spec/lib/roqua/rom_api/models/response_spec.rb
+- spec/lib/roqua/rom_api/protocol_subscriptions_spec.rb
+- spec/lib/roqua/rom_api/responses_spec.rb
 - spec/lib/roqua/rom_api/sessions/basic_auth_session_spec.rb
 - spec/lib/roqua/rom_api/start_fill_out_session_spec.rb
 - spec/lib/roqua/rom_api/start_protocol_subscription_spec.rb
@@ -187,10 +189,11 @@ specification_version: 4
 summary: API wrapper gem around RoQua's ROM API
 test_files:
 - spec/fabricators/basic_auth_session_fabricator.rb
-- spec/lib/roqua/rom_api/list_protocol_subscriptions_spec.rb
-- spec/lib/roqua/rom_api/list_responses_spec.rb
+- spec/lib/roqua/rom_api/endpoint_spec.rb
 - spec/lib/roqua/rom_api/models/protocol_subscription_spec.rb
 - spec/lib/roqua/rom_api/models/response_spec.rb
+- spec/lib/roqua/rom_api/protocol_subscriptions_spec.rb
+- spec/lib/roqua/rom_api/responses_spec.rb
 - spec/lib/roqua/rom_api/sessions/basic_auth_session_spec.rb
 - spec/lib/roqua/rom_api/start_fill_out_session_spec.rb
 - spec/lib/roqua/rom_api/start_protocol_subscription_spec.rb

data/lib/roqua/rom_api/list_protocol_subscriptions.rb

@@ -1,12 +0,0 @@
-module Roqua
-  module RomApi
-    # @api private
-    class ListProtocolSubscriptions < ActiveInteraction::Base
-      string :dossier_id
-      def execute
-        response = RomApi.basic_auth_session.get "/dossiers/#{dossier_id}/protocol_subscriptions"
-        response['protocol_subscriptions'].map { |s| Models::ProtocolSubscription.new(s) }
-      end
-    end
-  end
-end

data/lib/roqua/rom_api/list_responses.rb

@@ -1,12 +0,0 @@
-module Roqua
-  module RomApi
-    # @api private
-    class ListResponses < ActiveInteraction::Base
-      string :dossier_id
-      def execute
-        response = RomApi.basic_auth_session.get "/dossiers/#{dossier_id}/responses"
-        response['responses'].map { |r| Models::Response.new(r) }
-      end
-    end
-  end
-end