There can be a lot of “i’s” to dot and “t’s” to cross when integrating with any API. Here at Service Objects, we certainly recognize there can be a lot on the to-do list when starting an integration project. Integrating with our APIs is pretty straight forward, but we have developed a quick checklist that will ensure it is as easy as possible to follow our best practices.
Failover, Failover, Failover
Service Objects prides ourselves as having 99.999% server uptime. However, in the unlikely event that we do experience an issue with one of our servers, implementing a failover configuration is arguably the most important aspect of integrating with any of our APIs. Proper failover configuration will ensure that your application continues to operate unhindered in an event that the primary Service Objects web server is unavailable or not responding as expected. Below is an example (using C# syntax) of proper failover configuration.
try
{
string primaryurl = "https://sws.serviceobjects.com/av3/api.svc/GetBestMatches?BusinessName=" + businessName+ "&Address=" + address+ "&Address2=" + address2 + "&City=" + city + "&State=" + state + "&PostalCode=" + postalCode + "&LicenseKey=" + licenseKey;
string backupurl = "https://swsbackup.serviceobjects.com/av3/api.svc/GetBestMatches?BusinessName=" + businessName+ "&Address=" + address+ "&Address2=" + address2 + "&City=" + city + "&State=" + state + "&PostalCode=" + postalCode + "&LicenseKey=" + licenseKey;
BestMatchesResponse wsresponse = httpsGet(primaryurl);
if(wsresponse == null || (wsresponse.Error != null && wsresponse.Error.TypeCode == "3"))
{
throw new Exception();
}
}
catch
{
httpsGet(backupurl);
}
The example above is for our DOTS Address Validation 3 – US service, but this scenario will be relatively similar for our other services. The main thing to note is that the primary call is pointed towards sws.serviceobjects.com and the backup call within the catch statement is pointed to swsbackup.serviceobjects.com. In the event that the primary web server is unresponsive, producing strange errors or behaving abnormally, then the backup URL will be called and your application will continue to function as expected. Another important item to note is that proper failover will check the web service for an error response with a TypeCode of 3. This indicates that a fatal error has occurred in the web service and that the backup URL should be called. If you are using one of our older services, then the error object that service will return may be different (there will be only “Number” and “Desc” fields present in the Error object) and you will need to check for a Number value of 4 to indicate a fatal error.
URL Encoding
Properly encoding the URL you are using is also an item you will want to place on your to-do list for integration. If you are using a path parameter to access our services, then you’ll need to use what’s called RFC3986 encoding to encode your URLs. If you are using query string parameters to hit our services, then you can use the RFC3986 encoding or the older RCF2396 encoding. What do both of those RFC standards mean? Well in short, if you are using a query string URL, spaces can be acceptably replaced with “+” in the URL. If you’re using a path parameter URL, then spaces will have to be encoded with its hex equivalent %20. Using the RFC3986 standard encoding is generally the safer bet since it is the most accepted and newest.
Logging (we’re not talking cutting down trees)
We also highly recommend implementing some code that will log the requests and responses that our services provide. For the sake of customer privacy, we do not log information on our end. Logging can be a big help when troubleshooting your code. It can also be a big help to us if you ever need technical support. Since we do not log customer requests, it is very helpful for us to have the exact inputs or URL used when contacting our services. This will allow us to provide the stellar customer support that comes with integrating with a Service Objects’ API. If you do run into any issues, please send us your request and response as this will help us get to the bottom of whatever issue you are encountering as quickly as possible.
Null or Nothing Strings
Our output structure for most of our services is consistent and won’t change without notice. For the most part, our structure will stay the same and we’ll return the elements in our output structure as blank strings as opposed to null objects. That being said, we still highly recommend that your application performs null checks before using the response or any of the nested elements from our service. Even though the output structure for our services is very consistent, appropriately null checking our response can save you and your application a lot of headaches if something unexpected occurs.
URLs, IP Addresses and Whitelisting
Some clients or prospects will ask us if they can access our web services by IP address or whitelist the IP address in their firewall. Well, you certainly can, but we highly recommend whitelisting or hitting our web service by the domain URL. Most modern firewalls will support whitelisting domains by names and we highly recommend utilizing this. The reason being that IP addresses can and will change. We have a lot of backups and redundancy set up in our web services that will go unnoticed if you are accessing the service via a domain. If you absolutely need to hit our service by IP address or whitelist them like that, please reach out to our support team and we will be happy to make recommendations on best practices and provide you the information you will need.
Use Cases
If you are curious to know if you are understanding the results correctly or want to know if you are using the right operation to get the functionality you want, our developer guides can help provide more clarity about certain inputs and outputs from the service of choice.
Conclusion
As discussed, integrating with any API can bring up a lot of questions. If this list didn’t cover your questions or particular use case, please feel free to send your requests or questions to support@serviceobjects.com and we will be happy to help you get up and running with any of our 24 data validation APIs.
