From bb054d41742fde0b31923d438749fb1942f3812b Mon Sep 17 00:00:00 2001 From: Eric Devenport Date: Fri, 1 Nov 2024 16:13:14 -0600 Subject: [PATCH] Added ETAG Header for the US Address Enrichment API (#57) --- examples/us_enrichment_example.rb | 1 + lib/smartystreets_ruby_sdk/errors.rb | 2 + lib/smartystreets_ruby_sdk/exceptions.rb | 3 + .../status_code_sender.rb | 2 + .../us_enrichment/client.rb | 14 ++-- .../us_enrichment/geo_reference/lookup.rb | 5 +- .../us_enrichment/geo_reference/response.rb | 5 +- .../us_enrichment/lookup.rb | 5 +- .../property/financial/lookup.rb | 5 +- .../property/financial/response.rb | 5 +- .../property/principal/lookup.rb | 5 +- .../property/principal/response.rb | 5 +- .../us_enrichment/secondary/count/lookup.rb | 5 +- .../us_enrichment/secondary/count/response.rb | 5 +- .../us_enrichment/secondary/lookup.rb | 5 +- .../us_enrichment/secondary/response.rb | 5 +- .../us_enrichment/test_client.rb | 75 +++++++++++++++++++ 17 files changed, 125 insertions(+), 27 deletions(-) diff --git a/examples/us_enrichment_example.rb b/examples/us_enrichment_example.rb index 29e6ef7..b9b239d 100644 --- 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 index 56e24a5..578692f 100644 --- 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 index 5a4e252..58080f5 100644 --- 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 index 33a21b3..cbde340 100644 --- 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 index a5f74b8..39286d9 100644 --- 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 index 375e7fe..732feac 100644 --- 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 index e6009ad..503cc30 100644 --- 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 index 2280f78..185a7b1 100644 --- 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 index b3f98d6..3c2e728 100644 --- 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 index 975fb41..eeecb94 100644 --- 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 index e376b51..c851470 100644 --- 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 index 5913e7c..8febfa0 100644 --- 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 index f3172c8..4fe88c8 100644 --- 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 index 54fae39..c26c418 100644 --- 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 index 7d22886..48e8e1e 100644 --- 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 index b50c7d7..a62f214 100644 --- 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 index 56baf9d..714815a 100644 --- 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 \ No newline at end of file