Provide client and DTOs for US Extract API.

Author: mdwhatcott

us-extract-api/client.go

@@ -0,0 +1,47 @@
+package extract
+
+import (
+	"encoding/json"
+	"net/http"
+
+	"github.com/smartystreets/smartystreets-go-sdk"
+)
+
+// Client is responsible for sending requests to the us-extract-api.
+type Client struct {
+	sender sdk.RequestSender
+}
+
+// NewClient creates a client with the provided sender.
+func NewClient(sender sdk.RequestSender) *Client {
+	return &Client{sender: sender}
+}
+
+// SendBatch sends the batch of inputs, populating the output for each input if the batch was successful.
+func (c *Client) SendLookup(lookup *Lookup) error {
+	if lookup == nil || len(lookup.Text) == 0 {
+		return nil
+	} else if response, err := c.sender.Send(buildRequest(lookup)); err != nil {
+		return err
+	} else {
+		return deserializeResponse(response, lookup)
+	}
+}
+
+func deserializeResponse(response []byte, lookup *Lookup) error {
+	var extraction Result
+	err := json.Unmarshal(response, &extraction)
+	if err != nil {
+		return err
+	}
+	lookup.Result = &extraction
+	return nil
+}
+
+func buildRequest(lookup *Lookup) *http.Request {
+	request, _ := http.NewRequest("POST", extractURL, nil) // We control the method and the URL. This is safe.
+	lookup.populate(request)
+	return request
+}
+
+const extractURL = "/" // Remaining parts will be completed later by the sdk.BaseURLClient.

us-extract-api/client_test.go

@@ -0,0 +1,93 @@
+package extract
+
+import (
+	"errors"
+	"net/http"
+	"testing"
+
+	"github.com/smartystreets/assertions/should"
+	"github.com/smartystreets/gunit"
+)
+
+func TestClientFixture(t *testing.T) {
+	gunit.Run(new(ClientFixture), t)
+}
+
+type ClientFixture struct {
+	*gunit.Fixture
+
+	sender *FakeSender
+	client *Client
+
+	input *Lookup
+}
+
+func (f *ClientFixture) Setup() {
+	f.sender = &FakeSender{}
+	f.client = NewClient(f.sender)
+	f.input = new(Lookup)
+}
+
+func (f *ClientFixture) TestLookupSerializedAndSent__ResponseSuggestionsIncorporatedIntoLookup() {
+	f.sender.response = `{"meta": {"lines": 42}}`
+	f.input.Text = "42"
+
+	err := f.client.SendLookup(f.input)
+
+	f.So(err, should.BeNil)
+	f.So(f.sender.request, should.NotBeNil)
+	f.So(f.sender.request.Method, should.Equal, "POST")
+	f.So(f.sender.request.URL.Path, should.Equal, extractURL)
+	f.So(readBody(f.sender.request), should.Equal, "42")
+
+	f.So(f.input.Result, should.Resemble, &Result{Metadata: Metadata{Lines: 42}})
+}
+
+func (f *ClientFixture) TestNilLookupNOP() {
+	err := f.client.SendLookup(nil)
+	f.So(err, should.BeNil)
+	f.So(f.sender.request, should.BeNil)
+}
+
+func (f *ClientFixture) TestEmptyLookup_NOP() {
+	err := f.client.SendLookup(new(Lookup))
+	f.So(err, should.BeNil)
+	f.So(f.sender.request, should.BeNil)
+}
+
+func (f *ClientFixture) TestSenderErrorPreventsDeserialization() {
+	f.sender.err = errors.New("GOPHERS!")
+	f.sender.response = `{"meta": {"lines": 42}}` // would be deserialized if not for the err (above)
+	f.input.Text = "HI"
+
+	err := f.client.SendLookup(f.input)
+
+	f.So(err, should.NotBeNil)
+	f.So(f.input.Result, should.BeNil)
+}
+
+func (f *ClientFixture) TestDeserializationErrorPreventsDeserialization() {
+	f.sender.response = `I can't haz JSON`
+	f.input.Text = "HI"
+
+	err := f.client.SendLookup(f.input)
+
+	f.So(err, should.NotBeNil)
+	f.So(f.input.Result, should.BeNil)
+}
+
+/*////////////////////////////////////////////////////////////////////////*/
+
+type FakeSender struct {
+	callCount int
+	request   *http.Request
+
+	response string
+	err      error
+}
+
+func (f *FakeSender) Send(request *http.Request) ([]byte, error) {
+	f.callCount++
+	f.request = request
+	return []byte(f.response), f.err
+}

us-extract-api/extraction.go

@@ -0,0 +1,28 @@
+package extract
+
+import "github.com/smartystreets/smartystreets-go-sdk/us-street-api"
+
+// Result, Metadata, and ExtractedAddress represent all output fields documented here:
+// https://smartystreets.com/docs/cloud/us-extract-api#http-response
+type Result struct {
+	Metadata  Metadata           `json:"meta"`
+	Addresses []ExtractedAddress `json:"addresses"`
+}
+
+type Metadata struct {
+	Lines                   int  `json:"lines"`
+	Characters              int  `json:"character_count"`
+	Bytes                   int  `json:"bytes"`
+	Addresses               int  `json:"address_count"`
+	VerifiedAddresses       int  `json:"verified_count"`
+	ContainsNonASCIIUnicode bool `json:"unicode"`
+}
+
+type ExtractedAddress struct {
+	Text      string             `json:"text"`
+	Verified  bool               `json:"verified"`
+	Line      int                `json:"line"`
+	Start     int                `json:"start"`
+	End       int                `json:"end"`
+	APIOutput []street.Candidate `json:"api_output"`
+}

us-extract-api/lookup.go

@@ -0,0 +1,68 @@
+package extract
+
+import (
+	"io/ioutil"
+	"net/http"
+	"strconv"
+	"strings"
+)
+
+// Lookup represents all input fields documented here:
+// https://smartystreets.com/docs/cloud/us-extract-api#http-request-input-fields
+type Lookup struct {
+	Text string
+
+	HTML                    htmlPayload
+	Aggressive              bool
+	AddressesWithLineBreaks bool
+	AddressesPerLine        int
+
+	Result *Result
+}
+
+type htmlPayload string
+
+const (
+	HTMLUnspecified htmlPayload = ""      // Indicates that the server may decide if Lookup.Text is HTML or not.
+	HTMLYes         htmlPayload = "true"  // Indicates that the Lookup.Text is known to be HTML.
+	HTMLNo          htmlPayload = "false" // Indicates that the Lookup.Text is known to NOT be HTML.
+)
+
+func (l *Lookup) populate(request *http.Request) {
+	l.setQuery(request)
+	l.setBody(request)
+	l.setHeaders(request)
+}
+func (l *Lookup) setQuery(request *http.Request) {
+	query := request.URL.Query()
+
+	if l.HTML != HTMLUnspecified {
+		query.Set("html", string(l.HTML))
+	}
+
+	if l.Aggressive {
+		query.Set("aggressive", "true")
+	}
+
+	if l.AddressesWithLineBreaks {
+		query.Set("addr_line_breaks", "true")
+	}
+
+	if l.AddressesPerLine > 0 {
+		query.Set("addr_per_line", strconv.Itoa(l.AddressesPerLine))
+	}
+
+	request.URL.RawQuery = query.Encode()
+}
+func (l *Lookup) setBody(request *http.Request) {
+	if len(l.Text) == 0 {
+		return
+	}
+
+	body := strings.NewReader(l.Text)
+	request.Body = ioutil.NopCloser(body)
+	request.ContentLength = int64(body.Len())
+}
+func (l *Lookup) setHeaders(request *http.Request) {
+	request.Header.Set("Content-Type", "text/plain")
+}

us-extract-api/lookup_test.go

@@ -0,0 +1,78 @@
+package extract
+
+import (
+	"io/ioutil"
+	"net/http"
+	"net/url"
+	"testing"
+
+	"github.com/smartystreets/assertions/should"
+	"github.com/smartystreets/gunit"
+)
+
+func TestLookupFixture(t *testing.T) {
+	gunit.Run(new(LookupFixture), t)
+}
+
+type LookupFixture struct {
+	*gunit.Fixture
+
+	lookup  *Lookup
+	request *http.Request
+}
+
+func (f *LookupFixture) Setup() {
+	f.lookup = new(Lookup)
+	f.request, _ = http.NewRequest("POST", "/?hello=world", nil)
+}
+
+func (f *LookupFixture) query() url.Values {
+	return f.request.URL.Query()
+}
+
+func readBody(request *http.Request) string {
+	bytes, _ := ioutil.ReadAll(request.Body)
+	return string(bytes)
+}
+
+func (f *LookupFixture) TestPopulate_TextCopiedToBody() {
+	body := "Hello, World!"
+	f.lookup.Text = body
+
+	f.lookup.populate(f.request)
+
+	f.So(readBody(f.request), should.Equal, body)
+	f.So(f.request.ContentLength, should.Equal, len(body))
+	f.So(f.request.Header.Get("Content-Type"), should.Equal, "text/plain")
+}
+
+func (f *LookupFixture) TestPopulate_NothingSet_NothingAddedToQueryStringOrBody() {
+	f.lookup.populate(f.request)
+	f.So(f.query().Encode(), should.Equal, "hello=world")
+	f.So(f.request.Body, should.BeNil)
+	f.So(f.request.ContentLength, should.Equal, 0)
+}
+
+func (f *LookupFixture) TestPopulate_HTMLYes() {
+	f.lookup.HTML = HTMLYes
+	f.lookup.populate(f.request)
+	f.So(f.query().Get("html"), should.Equal, "true")
+}
+
+func (f *LookupFixture) TestPopulate_HTMLNo() {
+	f.lookup.HTML = HTMLNo
+	f.lookup.populate(f.request)
+	f.So(f.query().Get("html"), should.Equal, "false")
+}
+
+func (f *LookupFixture) TestPopulate_SimpleParameters_Set() {
+	f.lookup.AddressesPerLine = 42
+	f.lookup.AddressesWithLineBreaks = true
+	f.lookup.Aggressive = true
+
+	f.lookup.populate(f.request)
+
+	f.So(f.query().Get("aggressive"), should.Equal, "true")
+	f.So(f.query().Get("addr_line_breaks"), should.Equal, "true")
+	f.So(f.query().Get("addr_per_line"), should.Equal, "42")
+}

wireup/builder.go

@@ -9,6 +9,7 @@ import (
 	sdk "github.com/smartystreets/smartystreets-go-sdk"
 	internal "github.com/smartystreets/smartystreets-go-sdk/internal/sdk"
 	"github.com/smartystreets/smartystreets-go-sdk/us-autocomplete-api"
+	"github.com/smartystreets/smartystreets-go-sdk/us-extract-api"
 	"github.com/smartystreets/smartystreets-go-sdk/us-street-api"
 	"github.com/smartystreets/smartystreets-go-sdk/us-zipcode-api"
 )
@@ -128,6 +129,13 @@ func (b *ClientBuilder) BuildUSAutocompleteAPIClient() *autocomplete.Client {
 	return autocomplete.NewClient(b.buildHTTPSender())
 }
 
+// BuildUSExtractAPIClient builds the us-extract-api client using the provided
+// configuration details provided by other methods on the ClientBuilder.
+func (b *ClientBuilder) BuildUSExtractAPIClient() *extract.Client {
+	b.ensureBaseURLNotNil(defaultBaseURL_USExtractAPI)
+	return extract.NewClient(b.buildHTTPSender())
+}
+
 func (b *ClientBuilder) ensureBaseURLNotNil(u *url.URL) {
 	if b.baseURL == nil {
 		b.baseURL = u
@@ -158,4 +166,5 @@ var (
 	defaultBaseURL_USStreetAPI, _       = url.Parse("https://us-street.api.smartystreets.com")
 	defaultBaseURL_USZIPCodeAPI, _      = url.Parse("https://us-zipcode.api.smartystreets.com")
 	defaultBaseURL_USAutocompleteAPI, _ = url.Parse("https://us-autocomplete.api.smartystreets.com")
+	defaultBaseURL_USExtractAPI, _      = url.Parse("https://us-extract.api.smartystreets.com")
 )