Seriously, don't read this...
If you're not concerned with error handling, network hiccups, maximum uptime, security compliance, SLA, or any of the other really good practices out there, then this document isn't for you.
In addition to our Technical Requirements this document describes some of the best practices that you should follow when using any webservice. Failure to do these things may result in connectivity issues and service interruptions, neither of which are covered under our service level agreement.
- Persist Connections
- Asynchronous I/O
- Use HTTP Pipelining
- Batch Your Input
- Anticipate Timeouts
- Expect Change - Plan For It
There is significant overhead in establishing a TCP connection between client and server. Even in a tight loop, most HTTP clients by default naively destroy and re-create the TCP link between requests. We recommend keeping the connection open by using HTTP keep-alive. Exactly how you do this depends on your client environment and implementation. This should decrease latency by using the same TCP connection and, more significantly, the same TLS handshake.
Use HTTP Pipelining
Sending multiple requests while others are still in transit is known as HTTP pipelining. Rather than sending a request and waiting for its response before sending the next one, send a batch of requests in immediate sequence.
Batch Your Input
Whenever possible, combine multiple requests into a single request. Some SmartyStreets API endpoints in particular allow you to send batch requests. For example, you can send many addresses in a single POST request to /street-address rather than having to send as many GET requests. Our city/state/ZIP endpoint has a similar feature. The exact number of items you send per batch may vary; you should experiment to find the sweet spot. It might be about 25 or 30 addresses, or maybe 100.
Think of a timeout as a phone call. What do you do when you make an important phone call and no one answers? Do you give up or do you call back a little later?
Timeouts can happen because of network issues, severed fiber optic cables, dropped packets, Mynocks chewing on the power cables, or any of a hundred uncontrollable reasons. Here is an example of the various steps required in a typical HTTPS request.
Let's face it, timeouts happen. Say it again with me, "timeouts happen." Good, now you can plan for how you want to handle them.
Expect Change - Plan For It
Well-designed code should anticipate changes. SmartyStreets will, from time to time, make non-breaking changes to improve or enhance the service. These changes may introduce any of the following (list is not comprehensive): new features, new data points, new object keys or array elements, new headers, and new input parameters.
Remember, not all non-breaking changes introduce new features; they may also alter performance or response times. An important class of non-breaking changes are data updates. Updated data may change the exact result from a specific request. (For example, an address that is valid one month may not be valid the next. Such is the nature of the data.)
Whatever the non-breaking changes are, they are not expected to require customer action. Non-breaking changes occur on existing endpoints and do not introduce new versions.
SmartyStreets will make breaking changes from time to time. Because they alter the contract or may be expected to break client implementations, breaking changes are only introduced on newly-provisioned endpoints. Usually this provisioning is accomplished through versioning.
Customers who wish to adopt new changes may point their code to use a new endpoint as it becomes available. If the service does not support versioning or multiple endpoints, SmartyStreets will make its best efforts to notify customers of impending breaking changes by email, social media, or other means, with sufficient time for customers to take action. Customers using un-versioned services are responsible for being notified by having valid, useful contact information on file.
Customers who do not meet the technical requirements or follow best practices may unexpectedly experience non-breaking changes in a breaking way. However, in these situations, the change is still considered non-breaking.
Services in beta are subject to breaking changes even if the endpoint is not (yet) versioned.