Added ETAG Header for the US Address Enrichment API (#57)

smartystreets · Nov 1, 2024 · bb054d4 · bb054d4
1 parent 259a23a
commit bb054d4
Show file tree

Hide file tree

Showing 17 changed files with 125 additions and 27 deletions.
diff --git a/examples/us_enrichment_example.rb b/examples/us_enrichment_example.rb
@@ -33,6 +33,7 @@ def run
     lookup.city = "Somerville"
     lookup.state = "NJ"
     lookup.zipcode = "08876"
+    #lookup.etag = "AUBAGDQDAIGQYCYC"
 
     # Or, create a freeform lookup to search using a single line address
     freeform_lookup = SmartyStreets::USEnrichment::Lookup.new

diff --git a/lib/smartystreets_ruby_sdk/errors.rb b/lib/smartystreets_ruby_sdk/errors.rb
@@ -1,4 +1,6 @@
 module SmartyStreets
+  NOT_MODIFIED = 'Not Modified: This data has not been modified since the last request. Please remove the etag header to fetch this data'.freeze
+
   BAD_CREDENTIALS = 'Unauthorized: The credentials were provided incorrectly or did not match any existing,
  active credentials.'.freeze
 

diff --git a/lib/smartystreets_ruby_sdk/exceptions.rb b/lib/smartystreets_ruby_sdk/exceptions.rb
@@ -3,6 +3,9 @@ module SmartyStreets
   class SmartyError < StandardError
   end
 
+  class NotModifiedInfo < SmartyError
+  end
+
   class BadCredentialsError < SmartyError
   end
 

diff --git a/lib/smartystreets_ruby_sdk/status_code_sender.rb b/lib/smartystreets_ruby_sdk/status_code_sender.rb
@@ -35,6 +35,8 @@ def parse_rate_limit_response(response)
 
     def assign_exception(response)
       response.error = case response.status_code
+                         when '304'          
+                           NotModifiedInfo.new(NOT_MODIFIED)
                          when '401'
                            BadCredentialsError.new(BAD_CREDENTIALS)
                          when '402'

diff --git a/lib/smartystreets_ruby_sdk/us_enrichment/client.rb b/lib/smartystreets_ruby_sdk/us_enrichment/client.rb
@@ -83,6 +83,10 @@ def __send(lookup)
                 smarty_request = Request.new
 
                 return if lookup.nil?
+
+                if (!lookup.etag.nil?)
+                    smarty_request.header["ETAG"] = lookup.etag
+                end
                 if (lookup.smarty_key.nil?)
                     if (lookup.data_sub_set.nil?)
                         smarty_request.url_components = '/search/' + lookup.data_set
@@ -113,19 +117,19 @@ def __send(lookup)
                 results.each do |raw_result|
                     result = nil
                     if lookup.data_sub_set == "financial"
-                        result = USEnrichment::Property::Financial::Response.new(raw_result)
+                        result = USEnrichment::Property::Financial::Response.new(raw_result, response.header['etag'])
                     end
                     if lookup.data_sub_set == "principal"
-                        result = USEnrichment::Property::Principal::Response.new(raw_result)
+                        result = USEnrichment::Property::Principal::Response.new(raw_result, response.header['etag'])
                     end
                     if lookup.data_set == "geo-reference"
-                      result = USEnrichment::GeoReference::Response.new(raw_result)
+                      result = USEnrichment::GeoReference::Response.new(raw_result, response.header['etag'])
                     end
                     if lookup.data_set == "secondary"
                       if lookup.data_sub_set == "count"
-                        result = USEnrichment::Secondary::Count::Response.new(raw_result)
+                        result = USEnrichment::Secondary::Count::Response.new(raw_result, response.header['etag'])
                       elsif lookup.data_sub_set.nil?
-                        result = USEnrichment::Secondary::Response.new(raw_result)
+                        result = USEnrichment::Secondary::Response.new(raw_result, response.header['etag'])
                       end
                     end
                     output << result

diff --git a/lib/smartystreets_ruby_sdk/us_enrichment/geo_reference/lookup.rb b/lib/smartystreets_ruby_sdk/us_enrichment/geo_reference/lookup.rb
@@ -2,12 +2,13 @@ module SmartyStreets
   module USEnrichment
     module GeoReference
       class Lookup
-        attr_reader :smarty_key, :data_set, :data_sub_set
+        attr_reader :smarty_key, :data_set, :data_sub_set, :etag
 
-        def initialize(smarty_key)
+        def initialize(smarty_key, etag=nil)
           @smarty_key = smarty_key
           @data_set = 'geo-reference'
           @data_sub_set = nil
+          @etag = etag
         end
       end
     end

diff --git a/lib/smartystreets_ruby_sdk/us_enrichment/geo_reference/response.rb b/lib/smartystreets_ruby_sdk/us_enrichment/geo_reference/response.rb
@@ -4,12 +4,13 @@ module SmartyStreets
   module USEnrichment
     module GeoReference
       class Response
-        attr_reader :smarty_key, :data_set, :attributes
+        attr_reader :smarty_key, :data_set, :attributes, :etag
 
-        def initialize(obj)
+        def initialize(obj, etag=nil)
           @smarty_key = obj['smarty_key']
           @data_set = 'geo-reference'
           @attributes = Attributes.new(obj['attributes'])
+          @etag = etag
         end
       end
     end

diff --git a/lib/smartystreets_ruby_sdk/us_enrichment/lookup.rb b/lib/smartystreets_ruby_sdk/us_enrichment/lookup.rb
@@ -2,9 +2,9 @@
 module SmartyStreets
   module USEnrichment
     class Lookup < JSONAble
-      attr_accessor :smarty_key, :data_set, :data_sub_set, :freeform, :street, :city, :state, :zipcode
+      attr_accessor :smarty_key, :data_set, :data_sub_set, :freeform, :street, :city, :state, :zipcode, :etag
 
-      def initialize(smarty_key=nil, data_set=nil, data_sub_set=nil, freeform=nil, street=nil, city=nil, state=nil, zipcode=nil)
+      def initialize(smarty_key=nil, data_set=nil, data_sub_set=nil, freeform=nil, street=nil, city=nil, state=nil, zipcode=nil, etag=nil)
         @smarty_key = smarty_key
         @data_set = data_set
         @data_sub_set = data_sub_set
@@ -13,6 +13,7 @@ def initialize(smarty_key=nil, data_set=nil, data_sub_set=nil, freeform=nil, str
         @city = city
         @state = state
         @zipcode = zipcode
+        @etag = etag
       end
     end
   end

diff --git a/lib/smartystreets_ruby_sdk/us_enrichment/property/financial/lookup.rb b/lib/smartystreets_ruby_sdk/us_enrichment/property/financial/lookup.rb
@@ -3,12 +3,13 @@ module USEnrichment
         module Property
             module Financial
                 class Lookup
-                    attr_reader :smarty_key, :data_set, :data_sub_set
+                    attr_reader :smarty_key, :data_set, :data_sub_set, :etag
 
-                    def initialize(smarty_key)
+                    def initialize(smarty_key, etag=nil)
                         @smarty_key = smarty_key
                         @data_set = "property"
                         @data_sub_set = "financial"
+                        @etag = etag
                     end
                 end
             end

diff --git a/lib/smartystreets_ruby_sdk/us_enrichment/property/financial/response.rb b/lib/smartystreets_ruby_sdk/us_enrichment/property/financial/response.rb
@@ -5,13 +5,14 @@ module USEnrichment
         module Property
             module Financial
                 class Response
-                    attr_reader :smarty_key, :data_set, :data_sub_set, :attributes
+                    attr_reader :smarty_key, :data_set, :data_sub_set, :attributes, :etag
 
-                    def initialize(obj)
+                    def initialize(obj, etag=nil)
                         @smarty_key = obj['smarty_key']
                         @data_set = obj['data_set']
                         @data_sub_set = obj['data_sub_set']
                         @attributes = Attributes.new(obj['attributes'])
+                        @etag = etag
                     end
                 end
             end

diff --git a/lib/smartystreets_ruby_sdk/us_enrichment/property/principal/lookup.rb b/lib/smartystreets_ruby_sdk/us_enrichment/property/principal/lookup.rb
@@ -3,12 +3,13 @@ module USEnrichment
         module Property
             module Principal
                 class Lookup
-                    attr_reader :smarty_key, :data_set, :data_sub_set
+                    attr_reader :smarty_key, :data_set, :data_sub_set, :etag
 
-                    def initialize(smarty_key)
+                    def initialize(smarty_key, etag=nil)
                         @smarty_key = smarty_key
                         @data_set = "property"
                         @data_sub_set = "principal"
+                        @etag = etag
                     end
                 end
             end

diff --git a/lib/smartystreets_ruby_sdk/us_enrichment/property/principal/response.rb b/lib/smartystreets_ruby_sdk/us_enrichment/property/principal/response.rb
@@ -5,13 +5,14 @@ module USEnrichment
         module Property
             module Principal
                 class Response
-                    attr_reader :smarty_key, :data_set, :data_sub_set, :attributes
+                    attr_reader :smarty_key, :data_set, :data_sub_set, :attributes, :etag
 
-                    def initialize(obj)
+                    def initialize(obj, etag=nil)
                         @smarty_key = obj['smarty_key']
                         @data_set = obj['data_set']
                         @data_sub_set = obj['data_sub_set']
                         @attributes = Attributes.new(obj['attributes'])
+                        @etag = etag
                     end
                 end
             end

diff --git a/lib/smartystreets_ruby_sdk/us_enrichment/secondary/count/lookup.rb b/lib/smartystreets_ruby_sdk/us_enrichment/secondary/count/lookup.rb
@@ -3,12 +3,13 @@ module USEnrichment
     module Secondary
       module Count
         class Lookup
-          attr_reader :smarty_key, :data_set, :data_sub_set
+          attr_reader :smarty_key, :data_set, :data_sub_set, :etag
 
-          def initialize(smarty_key)
+          def initialize(smarty_key, etag=nil)
             @smarty_key = smarty_key
             @data_set = "secondary"
             @data_sub_set = "count"
+            @etag = etag
           end
         end
       end

diff --git a/lib/smartystreets_ruby_sdk/us_enrichment/secondary/count/response.rb b/lib/smartystreets_ruby_sdk/us_enrichment/secondary/count/response.rb
@@ -3,11 +3,12 @@ module USEnrichment
     module Secondary
       module Count
         class Response
-          attr_reader :smarty_key, :count
+          attr_reader :smarty_key, :count, :etag
 
-          def initialize(obj)
+          def initialize(obj, etag=nil)
             @smarty_key = obj['smarty_key']
             @count = obj['count']
+            @etag = etag
           end
         end
       end

diff --git a/lib/smartystreets_ruby_sdk/us_enrichment/secondary/lookup.rb b/lib/smartystreets_ruby_sdk/us_enrichment/secondary/lookup.rb
@@ -2,12 +2,13 @@ module SmartyStreets
   module USEnrichment
     module Secondary
       class Lookup
-        attr_reader :smarty_key, :data_set, :data_sub_set
+        attr_reader :smarty_key, :data_set, :data_sub_set, :etag
 
-        def initialize(smarty_key)
+        def initialize(smarty_key, etag=nil)
           @smarty_key = smarty_key
           @data_set = "secondary"
           @data_sub_set = nil
+          @etag = etag
         end
       end
     end

diff --git a/lib/smartystreets_ruby_sdk/us_enrichment/secondary/response.rb b/lib/smartystreets_ruby_sdk/us_enrichment/secondary/response.rb
@@ -6,15 +6,16 @@ module SmartyStreets
   module USEnrichment
     module Secondary
       class Response
-        attr_reader :smarty_key, :root_address, :aliases, :secondaries
+        attr_reader :smarty_key, :root_address, :aliases, :secondaries, :etag
 
-        def initialize(obj)
+        def initialize(obj, etag=nil)
           @smarty_key = obj['smarty_key']
           @root_address = Secondary::RootAddressEntry.new(obj['root_address'])
           if !obj['aliases'].nil?
             @aliases = createAliasesArray(obj['aliases'])
           end
           @secondaries = createSecondariesArray(obj['secondaries'])
+          @etag=etag
         end
 
         def createAliasesArray(obj)

diff --git a/test/smartystreets_ruby_sdk/us_enrichment/test_client.rb b/test/smartystreets_ruby_sdk/us_enrichment/test_client.rb
@@ -38,6 +38,21 @@ def test_financial_url_formatted_correctly
     assert_equal("street city state zipcode", sender.request.parameters["freeform"])
   end
 
+  def test_financial_etag_present
+    sender = RequestCapturingSender.new
+    client = SmartyStreets::USEnrichment::Client.new(sender, FakeDeserializer.new(nil))
+
+    lookup = SmartyStreets::USEnrichment::Lookup.new
+    lookup.street = "street"
+    lookup.city = "city"
+    lookup.state = "state"
+    lookup.zipcode = "zipcode"
+    lookup.etag = "etag"
+
+    client.send_property_financial_lookup(lookup)
+    assert_equal("etag", sender.request.header["ETAG"])
+  end
+
   def test_principal_url_formatted_correctly
     sender = RequestCapturingSender.new
     client = SmartyStreets::USEnrichment::Client.new(sender, FakeDeserializer.new(nil))
@@ -66,6 +81,21 @@ def test_principal_url_formatted_correctly
     assert_equal("street city state zipcode", sender.request.parameters["freeform"])
   end
 
+  def test_principal_etag_present
+    sender = RequestCapturingSender.new
+    client = SmartyStreets::USEnrichment::Client.new(sender, FakeDeserializer.new(nil))
+
+    lookup = SmartyStreets::USEnrichment::Lookup.new
+    lookup.street = "street"
+    lookup.city = "city"
+    lookup.state = "state"
+    lookup.zipcode = "zipcode"
+    lookup.etag = "etag"
+
+    client.send_property_principal_lookup(lookup)
+    assert_equal("etag", sender.request.header["ETAG"])
+  end
+
   def test_geo_reference_url_formatted_correctly
     sender = RequestCapturingSender.new
     client = SmartyStreets::USEnrichment::Client.new(sender, FakeDeserializer.new(nil))
@@ -93,6 +123,21 @@ def test_geo_reference_url_formatted_correctly
     assert_equal("/search/geo-reference", sender.request.url_components)
     assert_equal("street city state zipcode", sender.request.parameters["freeform"])
   end
+
+  def test_geo_reference_etag_present
+    sender = RequestCapturingSender.new
+    client = SmartyStreets::USEnrichment::Client.new(sender, FakeDeserializer.new(nil))
+
+    lookup = SmartyStreets::USEnrichment::Lookup.new
+    lookup.street = "street"
+    lookup.city = "city"
+    lookup.state = "state"
+    lookup.zipcode = "zipcode"
+    lookup.etag = "etag"
+
+    client.send_geo_reference_lookup(lookup)
+    assert_equal("etag", sender.request.header["ETAG"])
+  end
 
   def test_secondary_url_formatted_correctly
     sender = RequestCapturingSender.new
@@ -122,6 +167,21 @@ def test_secondary_url_formatted_correctly
     assert_equal("street city state zipcode", sender.request.parameters["freeform"])
   end
 
+  def test_secondary_etag_present
+    sender = RequestCapturingSender.new
+    client = SmartyStreets::USEnrichment::Client.new(sender, FakeDeserializer.new(nil))
+
+    lookup = SmartyStreets::USEnrichment::Lookup.new
+    lookup.street = "street"
+    lookup.city = "city"
+    lookup.state = "state"
+    lookup.zipcode = "zipcode"
+    lookup.etag = "etag"
+
+    client.send_secondary_lookup(lookup)
+    assert_equal("etag", sender.request.header["ETAG"])
+  end
+
   def test_secondary_count_url_formatted_correctly
     sender = RequestCapturingSender.new
     client = SmartyStreets::USEnrichment::Client.new(sender, FakeDeserializer.new(nil))
@@ -149,4 +209,19 @@ def test_secondary_count_url_formatted_correctly
     assert_equal("/search/secondary/count", sender.request.url_components)
     assert_equal("street city state zipcode", sender.request.parameters["freeform"])
   end
+
+  def test_financial_etag_present
+    sender = RequestCapturingSender.new
+    client = SmartyStreets::USEnrichment::Client.new(sender, FakeDeserializer.new(nil))
+
+    lookup = SmartyStreets::USEnrichment::Lookup.new
+    lookup.street = "street"
+    lookup.city = "city"
+    lookup.state = "state"
+    lookup.zipcode = "zipcode"
+    lookup.etag = "etag"
+
+    client.send_secondary_count_lookup(lookup)
+    assert_equal("etag", sender.request.header["ETAG"])
+  end
 end