ucb-hcm 3.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 62c9ba3f962308201cf3d2668c222e3b74615d7a5ae111335d09ab6c7334d181
-  data.tar.gz: a2cde1633debc69794e4d5ad4acc4755f258bb26da31ccf701623fbed0a09774
+  metadata.gz: 9dd61ba145d30df5ca3bebc81963f47dcb2ae2ff3216034c088f91ce8b76459f
+  data.tar.gz: f4037ac0a767966befa1b6f2e500167caa294afa70cf5f3f6627ed9b8ee6b2e2
 SHA512:
-  metadata.gz: 9bef13a7e84c972a74b126b32544cf15eeb77ba79d32fcba3e4c543a1f1e8d159e42bb17f9daa1ac44aadcd84ee7a0e2017aa4efceedbf8e3043815f98f09c91
-  data.tar.gz: 3a9feb88955fae6f323ca4cb10a6095a19b9e8ffe38da05686f15bc17eb8f82e670e8bce70bde31b8c7042c51fa7078da399addf24d02f0ee9c9190d6ded9b90
+  metadata.gz: dc1aecea9bb8fac982ae06bfd574f4fee4fa24300a2611355ff06e8e173303009c65f35d3c58a43ff180337485a31c6bd32b684d44ef229644ffd0c2c99ef2bc
+  data.tar.gz: c399c17bf5712a3accb5cde7835b0721e1dd76d2cab2e13305c50fb2b55a0a02acd456e378cf845de449c91805f96ba9414f23187fd8ca706584509b722bb256

data/.travis.yml

@@ -1,16 +1,18 @@
 branches:
   except:
-  - /^.*\/.*+$/
+  - "/^.*\\/.*+$/"
 language: ruby
 rvm:
-  - 2.5.1
+- 2.5.1
 install: true
 script:
-  - bin/setup
+- bin/setup
 before_deploy:
-  - git tag $TRAVIS_BRANCH-$TRAVIS_BUILD_NUMBER
+- git tag $TRAVIS_BRANCH-$TRAVIS_BUILD_NUMBER
 cache:
   directories:
-    - vendor/bundle
+  - vendor/bundle
 notifications:
-  slack: infinitered:4s2uT0dj614H6BUJteVhFGqo
+  slack: infinitered:4s2uT0dj614H6BUJteVhFGqo
+env:
+  secure: VLlNFC1FgeMxXwPmuHwDYQ4QAmv3M/1r3Eew2rjiNH5+t1h+pdZozMPiBJ8TrOicISz7qnf6Eb8kufN9TzW9oVQNSSLi3/FgPw78TV8tFcgG3ZGIOw1ZKzqKaiYDAXwHrWhcLytYaK187IloYQkmifSMf+qll9La8vAqHDGnLk8=

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+3.1.0
+-----
+
+Improved response parsing ([PR #5](https://github.com/ucb-ist-eas/ucb-hcm/pull/5)):
+
+  * Deprecated `Ucb::Hcm::Response#data` and `Ucb::Hcm::Response#response` - `data` was ambiguous as it sometimes returned an array and sometimes a hash
+  * Added `all` and `each` methods to `Ucb::Hcm::Response` for retrieving response data. The API returns response data as an array, even though it's often an array with one element. The client now better reflects that behavior
+  * Added `all_fetchers` and `each_fetcher` to wrap response data into [`Ucb::Hcm::DataFetcher`](https://github.com/ucb-ist-eas/ucb-hcm/blob/master/lib/ucb/hcm/data_fetcher.rb) instances
+
+3.0.0
+-----
+
+Switch to v3 of the HCM API ([PR #2](https://github.com/ucb-ist-eas/ucb-hcm/pull/2))
+

data/README.md

@@ -2,7 +2,7 @@
 
 Ucb::Hcm is a lightweight ruby wrapper around [UC Berkeley's Human Capital Management API](https://api-central.berkeley.edu/api/14/interactive-docs).
 
-Version 1.0 of this gem supports the v2 API, documented in the link above. UCB now has v3 of the API - we'll skip version 2.0 of the gem and make version 3.0 support the v3 API.
+The current version (3.x) is intended for v3 of the HCM API. If you need to access v2, you should use 1.0 of this gem.
 
 ## Installation
 
@@ -25,20 +25,24 @@ Configure your app with your API credentials from [UCB's API Central](https://ap
     Ucb::Hcm.configure do |hcm|
       hcm.app_id  = "APP_ID"
       hcm.app_key = "APP_KEY"
-      hcm.endpoint = "https://apis.berkeley.edu/dev/hr/v3"
+      hcm.endpoint = "https://apis.berkeley.edu/uat/hr/v3"
     end
 
 ## Usage
 
 :rotating_light: Note: Version 3.x of this gem only supports v3 of the API. :rotating_light:
 
+See the [API documentation](https://api-central.berkeley.edu/api/14/interactive-docs) for details on the different endpoints and what they return.
+
+Note that the main part of the returned payload (`["response"]`) is always an `Array`. It will often have only one element, but there could be more, even if you're not expecting them. To make certain you're getting all the data you asked for, be sure to iterate over the payload.
+
 ### Fetch Employees
 
 ```ruby
     client = Ucb::Hcm::Client.new
     response = client.get("/employees", { limit: 20, previous: 0, next: 20 })
 
-    >> response.data
+    >> response.all
     => [
           {
             "identifiers"=> [
@@ -61,20 +65,22 @@ Configure your app with your API credentials from [UCB's API Central](https://ap
     client = Ucb::Hcm::Client.new
     response = client.get("/employees/10272831", {"id-type" => "hr-employee-id"})
 
-    >> response.data
-    => {
-          "identifiers" => [
-            {"type" => "campus-uid", "id" => "20108691"}, {"type" => "campus-solutions-id"}, {"type" => "student-id"}, {"type" => "hr-employee-id", "id" => "10272831"}, {"type" => "legacy-hr-employee-id"}, {"type" => "calnet-id"}
-          ],
-          "names" => [{
-            "type "= >{"code" => "PRI", "description" => "Primary"},
-            "familyName" => "Kumar",
-            "givenName" => "Siri",
-            "lastChangedBy" => {"id" => "10000499"},
-            "fromDate" => "2018-10-01"
-          }],
-          ...
-        }
+    >> response.all
+    => [
+         {
+            "identifiers" => [
+              {"type" => "campus-uid", "id" => "20108691"}, {"type" => "campus-solutions-id"}, {"type" => "student-id"}, {"type" => "hr-employee-id", "id" => "10272831"}, {"type" => "legacy-hr-employee-id"}, {"type" => "calnet-id"}
+            ],
+            "names" => [{
+              "type "= >{"code" => "PRI", "description" => "Primary"},
+              "familyName" => "Kumar",
+              "givenName" => "Siri",
+              "lastChangedBy" => {"id" => "10000499"},
+              "fromDate" => "2018-10-01"
+            }],
+            ...
+          }
+        ]
 
 ```
 
@@ -84,23 +90,165 @@ Configure your app with your API credentials from [UCB's API Central](https://ap
     client = Ucb::Hcm::Client.new
     response = client.get("/employees/10272831/jobs", {"id-type" => "hr-employee-id"})
 
-    # The jobs api sometimes returns an array with the first element
-    # containing the real job data and the second an empty hash :(.
-    # For example: [{<real_data>}, {}]
-    >> response.data.first["jobs"]
+    >> response.all
     => [
-        {
-          "number" => 0,
-          "sequence" => 0,
-          "type" => {
-            "code" => "2",
-            "description" => "Staff: Career"
-          },
-          ...
+         {
+            "identifiers" => [
+              {"type" => "campus-uid", "id" => "20108691"}, {"type" => "campus-solutions-id"}, {"type" => "student-id"}, {"type" => "hr-employee-id", "id" => "10272831"}, {"type" => "legacy-hr-employee-id"}, {"type" => "calnet-id"}
+            ],
+            "jobs" => [
+              {
+                "number" => 0,
+                "sequence" => 0,
+                "type" => {
+                  "code" => "2",
+                  "description" => "Staff: Career"
+                },
+                ...
+              }
+              ...
+            ]
         }
     ]
 ```
 
+## Parsing The Response
+
+All of the API calls return an instance of `Ucb::Hcm::Response`. There are various ways to get to the underlying data, depending on your needs.
+
+### Checking The Response Status
+
+You can find out if the call was successful by checking the return code, or just calling `success?`:
+
+```ruby
+response = client.get("/employees/10272831/jobs", {"id-type" => "hr-employee-id"})
+response.code
+=> 200
+
+response.success?
+=> true
+```
+
+Any status code other than `200` will cause `success?` to return false
+
+### Extracting The Response Data: The Low-Level Approach
+
+Calling `raw_response` will give the response object of the underlying HTTP library (currently `HTTParty::Response`). That object behaves like a hash, so you can access any part of the payload directly:
+
+```ruby
+response = client.get("/employees/10272831/jobs", {"id-type" => "hr-employee-id"})
+response.raw_response["source"]
+=> "UCB-HR-PATH-DB"
+```
+
+The `all` method will return the contents of the `response` portion of the payload - this is where the meat of the data is usually found. The `response` node is always an `Array` of `Hash` objects even if one element is expected:
+
+```ruby
+response = client.get("/employees/10272831/jobs", {"id-type" => "hr-employee-id"})
+
+response.all
+=> [
+     {
+        "identifiers" => [
+          {"type" => "campus-uid", "id" => "20108691"}, {"type" => "campus-solutions-id"}, {"type" => "student-id"}, {"type" => "hr-employee-id", "id" => "10272831"}, {"type" => "legacy-hr-employee-id"}, {"type" => "calnet-id"}
+        ],
+        "jobs" => [
+          {
+            "number" => 0,
+            "sequence" => 0,
+            "type" => {
+              "code" => "2",
+              "description" => "Staff: Career"
+            },
+            ...
+          }
+          ...
+        ]
+    }
+]
+
+response.all.first["jobs"].first["number"]
+=> 0
+```
+
+You can also iterate through each of the response items with the `each` method:
+
+```ruby
+response = client.get("/employees/10272831/jobs", {"id-type" => "hr-employee-id"})
+
+response.each do |item|
+  puts item["jobs"].first["number"]
+end
+=> 0
+```
+
+### Extracting The Response Data Using DataFetcher
+
+The payloads from the HCM API are often very large and deeply nested, so navigating them as raw hashes can be a little cumbersome. To help get around this, it's possible to read the response data using the `Ucb::Hcm::DataFetcher` object.
+
+#### DataFetcher Overview
+
+A `DataFetcher` takes a hash when initialized and it can then be safely navigated using dot notation:
+
+```ruby
+data = {foo: "bar", baz: { bam: "bang" }}
+fetcher = Ucb::Hcm::DataFetcher.new(data)
+fetcher.baz.bam.value
+=> "bang"
+```
+
+You need to call `value` when you've reached the node you're trying to read.
+
+If you hit a node that contains an array, you can use the usual `Array` methods to navigate through them:
+
+```ruby
+data = {foo: "bar", baz: [{ bam: "bang" }]} # baz is an Array this time
+fetcher = Ucb::Hcm::DataFetcher.new(data)
+fetcher.baz.first.bam.value
+=> "bang"
+
+fetcher.baz[0].bam.value
+=> "bang"
+```
+
+Apart from the conciseness of the syntax, `DataFetcher` has another advantage over digging through hashes, as it will handle nodes that are `nil` without raising an exception:
+
+```ruby
+fetcher.baz.this_is_not_a_real_node.bam.value
+=> nil
+```
+
+If any part of the traversal yields `nil`, the call to `value` will return `nil` but you can change this by passing a different default to the `value` call:
+
+```ruby
+fetcher.baz.this_is_not_a_real_node.bam.value("oops!")
+=> "oops!"
+```
+
+#### Getting DataFetchers From A Response
+
+You can access an API payload with `DataFetcher` objects by calling `all_fetchers` or `each_fetcher` on a `Response` instance. These are equivalent to `all` and `each` (described earlier) but they return `DataFetcher` instances rather than hashes:
+
+```ruby
+response = client.get("/employees/10272831/jobs", {"id-type" => "hr-employee-id"})
+
+response.all.first.class
+=> Hash
+
+response.all_fetchers.first.class
+=> Ucb::Hcm::DataFetcher
+
+response.each do |item|
+  p item.class
+end
+=> Hash
+
+response.each_fetcher do |item|
+  p item.class
+end
+=> Ucb::Hcm::DataFetcher
+```
+
 ## Contributing
 
 1. Fork it ( https://github.com/[my-github-username]/ucb-hcm/fork )

data/lib/ucb/hcm/configuration.rb

@@ -5,7 +5,7 @@ module Ucb
       VALID_OPTIONS_KEYS    = [:app_id, :app_key, :format].freeze
       VALID_CONFIG_KEYS     = VALID_CONNECTION_KEYS + VALID_OPTIONS_KEYS
 
-      DEFAULT_ENDPOINT    = 'https://apis.berkeley.edu/test/hr/v3'
+      DEFAULT_ENDPOINT    = 'https://apis.berkeley.edu/uat/hr/v3'
       DEFAULT_METHOD      = :get
       DEFAULT_USER_AGENT  = "Ucb::Hcm API Ruby Gem #{Ucb::Hcm::VERSION}".freeze
 

data/lib/ucb/hcm/data_fetcher.rb

@@ -0,0 +1,72 @@
+require "hashie"
+
+# This is a utility class that makes it easy to grab deeply nested values safely. Given a Hash like:
+# fetcher = DataFetcher.new(
+#   {
+#     "names"=>[{
+#       "type"=>{"code"=>"PRI", "description"=>"Primary"},
+#       "familyName"=>"Montalban",
+#       "givenName"=>"Ricardo",
+#     }],
+#   }
+#  )
+#
+# you could access the name code like this:
+#   fetcher.names.first.type.code.value
+#
+# If any part of the path is missing or nil, no exception will be raised, and the value() call
+# will return nil.
+#
+# By default, you'll get nil back if any part of call chain is missing or nil. If you want a different
+# fallback value, you can pass that to value(). This would return "not found":
+#   fetcher.thisIsNotInTheResponseHash.first.type.code.value("not found")
+#
+# DataFetcher will accept node names in camel case or snake case. The following are equivalent:
+#   fetcher.names.first.familyName.value
+#   fetcher.names.first.family_name.value
+#
+
+module Ucb
+  module Hcm
+    class DataFetcher
+      attr_reader :current_value
+
+      def initialize(raw_data)
+        @original_value = raw_data
+        reset_current_value(raw_data)
+      end
+
+      def value(default = nil)
+        (@current_value || default).tap do
+          reset_current_value(@original_value)
+        end
+      end
+
+      # This is where the fetching logic happens - each time we're given a value to find, we store
+      # that value as @current_value and wait for the next call. If we ever get nil, then none of the
+      # subsequent calls matter, so we short-circuit them.
+      def method_missing(method, *args)
+        return self if @current_value.nil?
+
+        normalized_method = camelize(method)
+        if @current_value.respond_to?(normalized_method)
+          @current_value = @current_value.send(normalized_method, *args)
+        else
+          @current_value = nil
+        end
+        self
+      end
+
+      private
+
+      def camelize(str)
+        str.to_s.gsub(/_([a-z])/) { "#{$1.upcase}" }
+      end
+
+      def reset_current_value(hash)
+        @current_value = Hashie::Mash.new(hash)
+      end
+
+    end
+  end
+end

data/lib/ucb/hcm/response.rb

@@ -1,25 +1,53 @@
+require "hashie"
+require_relative "data_fetcher"
+
 module Ucb
   module Hcm
     class Response
       extend Forwardable
 
-      attr_reader :raw_response, :data_fetcher
+      attr_reader :raw_response
 
-      def_delegators :response, :code
+      def_delegators :raw_response, :code
 
       def initialize(raw_response)
         @raw_response = raw_response
       end
 
-      def response
+      def success?
+        code == 200
+      end
+
+      def raw
         raw_response
       end
 
-      def success?
-        code == 200
+      def all
+        raw_response&.fetch("response", []) || []
+      end
+
+      def all_fetchers
+        all.map { |item| Ucb::Hcm::DataFetcher.new(item) }
+      end
+
+      def each
+        all.each { |item| yield item }
+      end
+
+      def each_fetcher
+        all.each { |item| yield Ucb::Hcm::DataFetcher.new(item) }
+      end
+
+      ##############################
+      # deprecations
+
+      def response
+        warn "Ucb::Hcm#response is deprecated and will be removed in future versions - use #raw_response instead"
+        raw_response
       end
 
       def data
+        warn "Ucb::Hcm#data is deprecated and will be removed in future versions - use #raw_response['response'] instead"
         if raw_response["response"]&.count == 1
           raw_response["response"]&.first
         else
@@ -27,9 +55,6 @@ module Ucb
         end
       end
 
-      def data_fetcher=(block)
-        @data_fetcher = block
-      end
     end
   end
-end
+end

data/lib/ucb/hcm/version.rb

@@ -1,5 +1,5 @@
 module Ucb
   module Hcm
-    VERSION = "3.0"
+    VERSION = "3.1.0"
   end
 end

data/spec/spec_helper.rb

@@ -1,3 +1,63 @@
 # spec/spec_helper.rb
 require 'ucb/hcm'
 require 'support/test_credentials'
+require 'support/vcr'
+
+TEST_RESPONSE = {
+  "source"=>"UCB-HR-PATH-DB",
+  "correlationId"=>"2cf1e603-95cb-405c-a0ad-535b468e0a11",
+  "response"=>[
+    {
+      "identifiers"=>[
+        {"type"=>"hr-employee-id", "id"=>"1234567"},
+        {"type"=>"campus-uid", "id"=>"12346"},
+      ],
+      "names"=>[{
+        "type"=>{"code"=>"PRI", "description"=>"Primary"},
+        "familyName"=>"Montalban",
+        "givenName"=>"Ricardo",
+        "middleName"=>"Roark",
+        "lastChangedBy"=>{"id"=>"UC_AROY"},
+        "fromDate"=>"2015-08-01"
+      }],
+      "gender"=>{
+        "genderOfRecord"=>{
+          "code"=>"M", "description"=>"Male", "fromDate"=>"2015-08-01"
+        }
+      },
+      "emails"=>[{
+        "type"=>{
+          "code"=>"BUSN", "description"=>"Business"
+        },
+        "emailAddress"=>"rmontalban@berkeley.edu",
+        "primary"=>true
+      }]
+    },
+    {
+      "identifiers"=>[
+        {"type"=>"hr-employee-id", "id"=>"9876543"},
+        {"type"=>"campus-uid", "id"=>"9876"},
+      ],
+      "names"=>[{
+        "type"=>{"code"=>"PRI", "description"=>"Primary"},
+        "familyName"=>"McCoy",
+        "givenName"=>"Julie",
+        "lastChangedBy"=>{"id"=>"UC_AROY"},
+        "fromDate"=>"2014-08-01"
+      }],
+      "gender"=>{
+        "genderOfRecord"=>{
+          "code"=>"F", "description"=>"Female", "fromDate"=>"2015-08-01"
+        }
+      },
+      "emails"=>[{
+        "type"=>{
+          "code"=>"BUSN", "description"=>"Business"
+        },
+        "emailAddress"=>"jmccoy@berkeley.edu",
+        "primary"=>true
+      }]
+    }
+  ]
+}
+

data/spec/support/vcr.rb

@@ -0,0 +1,43 @@
+require 'openssl'
+require 'vcr'
+
+class VcrEncryptor
+
+  def encrypt(string)
+    cipher = init_cipher(:encrypt)
+    cipher.update(string) + cipher.final
+  end
+
+  def decrypt(string)
+    decipher = init_cipher(:decrypt)
+    decipher.update(string) + decipher.final
+  end
+
+  private
+
+  def init_cipher(type)
+    OpenSSL::Cipher::AES256.new(:CBC).tap do |cipher|
+      type == :encrypt ? cipher.encrypt : cipher.decrypt
+      cipher.key = ENV['RAILS_MASTER_KEY']
+    end
+  end
+
+end
+
+encrypted_serializer = Object.new
+class << encrypted_serializer
+  def file_extension; "enc"; end
+  def serialize(hash); VcrEncryptor.new.encrypt(hash.to_json); end
+  def deserialize(string); JSON.parse(VcrEncryptor.new.decrypt(string)); end
+end
+
+
+VCR.configure do |c|
+  c.cassette_library_dir = "spec/cassettes"
+  c.cassette_serializers[:enc] = encrypted_serializer
+  c.default_cassette_options = { :serialize_with => :enc }
+  c.hook_into :webmock
+  c.configure_rspec_metadata!
+  c.ignore_localhost = true
+end
+

data/spec/ucb/hcm/api_spec.rb

@@ -7,54 +7,55 @@ RSpec.describe 'api' do
   end
 
   describe "#get" do
-    describe "GET /employees/:id" do
+    describe "GET /employees/:id", :vcr do
       it "returns employee data w/ valid id & legacy-hr-employee-type" do
-        response = @client.get("/employees/10135532", {"id-type" => "hr-employee-id"})
+        response = @client.get("/employees/10161331", {"id-type" => "hr-employee-id"})
 
         expect(response.success?).to eq true
-        expect(response.data["identifiers"].first.has_key?("type")).to eq true
+        data = response.all.first
+        expect(data["identifiers"].first.has_key?("type")).to eq true
 
-        names = response.data["names"]
+        names = data["names"]
         expect(names.empty? || names.first.has_key?("familyName")).to eq true
 
-        addresses = response.data["addresses"]
+        addresses = data["addresses"]
         expect(addresses.empty? || addresses.first.has_key?("address1")).to eq true
 
-        emails = response.data["emails"]
+        emails = data["emails"]
         expect(emails.empty? || emails.first.has_key?("emailAddress")).to eq true
 
-        phones = response.data["phones"]
+        phones = data["phones"]
         expect(phones.empty? || phones.first.has_key?("number")).to eq true
       end
 
-      # this used to return 404 - now it just seems to default to hr-employee-id
+      # this should return 404
       it "succeeds with invalid id-type" do
         response = @client.get("/employees/10135532", {"id-type" => "invalid-type"})
 
-        expect(response.success?).to be true
+        expect(response.success?).to be false
       end
 
-      # this used to return 500 - now it returns 200 with an empty response
+      # this should return 400
       it "returns empty response if id is invalid" do
         response = @client.get("/employees/invalidId", {"id-type" => "legacy-hr-employee-id"})
 
-        expect(response.success?).to be true
-        expect(response.data).to be_nil
+        expect(response.success?).to be false
+        expect(response.all.first).to be_nil
       end
     end
 
-    describe "fetch employee jobs" do
+    describe "fetch employee jobs", :vcr do
       it "returns all an employees jobs" do
-        response = @client.get("/employees/010789601/jobs", {"id-type" => "legacy-hr-employee-id"})
+        response = @client.get("/employees/10161331/jobs", {"id-type" => "hr-employee-id"})
 
         expect(response.success?).to eq true
 
-        job = response.data["jobs"].first
+        job = response.all.first["jobs"].first
         expect(job.has_key?("compensation")).to eq true
       end
     end
 
-    describe "GET /employees" do
+    describe "GET /employees", :vcr do
       it "supports pagination" do
         params = {
           limit: 5,
@@ -64,7 +65,7 @@ RSpec.describe 'api' do
 
         response = @client.get("/employees", params)
 
-        expect(response.data.count).to eq 5
+        expect(response.all.count).to eq 5
       end
     end
   end

data/spec/ucb/hcm/data_fetcher_spec.rb

@@ -0,0 +1,41 @@
+require "spec_helper"
+require "pry"
+
+RSpec.describe "response" do
+  let(:fetcher) { Ucb::Hcm::DataFetcher.new(TEST_RESPONSE["response"].first) } # TEST_RESPONSE defined in spec_helper
+
+  it "can respond to dot notation" do
+    expect(fetcher.gender.genderOfRecord.code.value).to eq("M")
+  end
+
+  it "returns nil if any part of the call chain cannot be found in the response" do
+    expect(fetcher.notInTheResponse.genderOfRecord.code.value).to eq(nil)
+  end
+
+  it "returns the specified default value if any part of the call chain cannot be found in the response" do
+    expect(fetcher.notInTheResponse.genderOfRecord.code.value("not found")).to eq("not found")
+  end
+
+  it "can respond to snake case as well as camel case" do
+    expect(fetcher.gender.gender_of_record.from_date.value).to eq("2015-08-01")
+  end
+
+  it "can handle arrays in the call chain" do
+    expect(fetcher.names.first.type.code.value).to eq("PRI")
+  end
+
+  it "can be reused" do
+    fetcher.names.first.type.code.value
+    expect(fetcher.names.first.type.code.value).to eq("PRI")
+  end
+
+  it "can handle arrays with bracket notation" do
+    expect(fetcher.names[0].type.code.value).to eq("PRI")
+  end
+
+  it "can respond to accessing the data as a hash" do
+    expect(fetcher["names"].first["type"]["code"].value).to eq("PRI")
+  end
+
+end
+

data/spec/ucb/hcm/request_spec.rb

@@ -26,8 +26,8 @@ describe 'request' do
   end
 
   describe 'get' do
-    it 'performs a get request' do
-      response = @client.get("/employees/010789601", {"id-type" => "legacy-hr-employee-id"})
+    it 'performs a get request', :vcr do
+      response = @client.get("/employees/10161331", {"id-type" => "hr-employee-id"})
       expect(response).to be_an_instance_of Ucb::Hcm::Response
       expect(response.success?).to eq true
     end

data/spec/ucb/hcm/response_spec.rb

@@ -0,0 +1,61 @@
+require "spec_helper"
+
+RSpec.describe "response" do
+  let(:raw_response) { TEST_RESPONSE } # TEST_RESPONSE defined in spec_helper
+  let(:response) {
+    allow(raw_response).to receive(:code) { "200" }
+    Ucb::Hcm::Response.new(raw_response)
+  }
+
+  it "returns the HTTP status code" do
+    expect(response.code).to eq("200")
+  end
+
+  it "returns the underlying JSON data" do
+    expect(response.all).to eq(TEST_RESPONSE["response"])
+  end
+
+  it "can iterate through the responses" do
+    count = 0
+    response.each do |item|
+      expect(item["names"]).to be_a(Array)
+      count += 1
+    end
+    expect(count).to eq(2)
+  end
+
+  it "returns an empty list when calling #all if the response was empty" do
+    response = Ucb::Hcm::Response.new(nil)
+    expect(response.all).to be_empty
+  end
+
+  it "returns an empty list when calling #all if the response does not have a 'response' element" do
+    response = Ucb::Hcm::Response.new({foo: "bar"})
+    expect(response.all).to be_empty
+  end
+
+  it "returns a working iterator if the response was empty" do
+    response = Ucb::Hcm::Response.new({foo: "bar"})
+    count = 0
+    response.each do |item|
+      count += 1
+    end
+    expect(count).to eq(0)
+  end
+
+  it "returns the underlying JSON data wrapped in DataFetcher instances" do
+    response_fetchers = TEST_RESPONSE["response"].map { |item| Ucb::Hcm::DataFetcher.new(item) }
+    expect(response.all_fetchers.map(&:class)).to eq(response_fetchers.map(&:class))
+  end
+
+  it "can interate through a list of DataFetcher instances" do
+    count = 0
+    response.each_fetcher do |item|
+      expect(item).to be_a(Ucb::Hcm::DataFetcher)
+      count += 1
+    end
+    expect(count).to eq(2)
+  end
+
+end
+

data/ucb-hcm.gemspec

@@ -20,10 +20,14 @@ Gem::Specification.new do |spec|
 
   spec.add_runtime_dependency "activesupport"
   spec.add_runtime_dependency "httparty", "~> 0.13.1"
+  spec.add_runtime_dependency "hashie"
   spec.add_development_dependency "bundler", "~> 1.6"
   spec.add_development_dependency "rake"
-  spec.add_development_dependency 'pry'
-  spec.add_development_dependency 'byebug'
-  spec.add_development_dependency 'rspec-core'
-  spec.add_development_dependency 'rspec-expectations'
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency "byebug"
+  spec.add_development_dependency "rspec-core"
+  spec.add_development_dependency "rspec-expectations"
+  spec.add_development_dependency "rspec-mocks"
+  spec.add_development_dependency "vcr"
+  spec.add_development_dependency "webmock"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ucb-hcm
 version: !ruby/object:Gem::Version
-  version: '3.0'
+  version: 3.1.0
 platform: ruby
 authors:
 - Peter Philips
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-02-07 00:00:00.000000000 Z
+date: 2019-03-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -40,6 +40,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.13.1
+- !ruby/object:Gem::Dependency
+  name: hashie
+  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'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -124,6 +138,48 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec-mocks
+  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: vcr
+  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: webmock
+  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'
 description: Lightweight wrapper for the UCB HCM Api - https://developer.berkeley.edu/apidocs/employee
 email:
 - hello@infinite.red
@@ -135,6 +191,7 @@ files:
 - ".gitignore"
 - ".ruby-version"
 - ".travis.yml"
+- CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -143,15 +200,25 @@ files:
 - lib/ucb/hcm/api.rb
 - lib/ucb/hcm/client.rb
 - lib/ucb/hcm/configuration.rb
+- lib/ucb/hcm/data_fetcher.rb
 - lib/ucb/hcm/request.rb
 - lib/ucb/hcm/response.rb
 - lib/ucb/hcm/version.rb
+- spec/cassettes/api/_get/GET_/employees/_id/returns_employee_data_w/_valid_id_legacy-hr-employee-type.enc
+- spec/cassettes/api/_get/GET_/employees/_id/returns_empty_response_if_id_is_invalid.enc
+- spec/cassettes/api/_get/GET_/employees/_id/succeeds_with_invalid_id-type.enc
+- spec/cassettes/api/_get/GET_/employees/supports_pagination.enc
+- spec/cassettes/api/_get/fetch_employee_jobs/returns_all_an_employees_jobs.enc
+- spec/cassettes/request/get/performs_a_get_request.enc
 - spec/spec_helper.rb
 - spec/support/test_credentials.rb
+- spec/support/vcr.rb
 - spec/ucb/hcm/api_spec.rb
 - spec/ucb/hcm/configuration_spec.rb
+- spec/ucb/hcm/data_fetcher_spec.rb
 - spec/ucb/hcm/hcm_spec.rb
 - spec/ucb/hcm/request_spec.rb
+- spec/ucb/hcm/response_spec.rb
 - ucb-hcm.gemspec
 homepage: https://infinite.red
 licenses:
@@ -178,9 +245,18 @@ signing_key:
 specification_version: 4
 summary: Ucb HCM - Human Capital Management API gem
 test_files:
+- spec/cassettes/api/_get/GET_/employees/_id/returns_employee_data_w/_valid_id_legacy-hr-employee-type.enc
+- spec/cassettes/api/_get/GET_/employees/_id/returns_empty_response_if_id_is_invalid.enc
+- spec/cassettes/api/_get/GET_/employees/_id/succeeds_with_invalid_id-type.enc
+- spec/cassettes/api/_get/GET_/employees/supports_pagination.enc
+- spec/cassettes/api/_get/fetch_employee_jobs/returns_all_an_employees_jobs.enc
+- spec/cassettes/request/get/performs_a_get_request.enc
 - spec/spec_helper.rb
 - spec/support/test_credentials.rb
+- spec/support/vcr.rb
 - spec/ucb/hcm/api_spec.rb
 - spec/ucb/hcm/configuration_spec.rb
+- spec/ucb/hcm/data_fetcher_spec.rb
 - spec/ucb/hcm/hcm_spec.rb
 - spec/ucb/hcm/request_spec.rb
+- spec/ucb/hcm/response_spec.rb