The Service Objects web services support integrations using the industry standard HTTP GET, POST, and SOAP protocols. They also allow for return objects in both XML and JSON markup languages. In recent years HTTP POST and SOAP requests have often taken a back seat to the GET protocol. This is in part due to the abundance of APIs following the RESTful architecture pattern. The goal of this blog is to help clear up a common misconception about what our responses mean as they relate to RESTful design.
Our web services all follow a standard rigid format that allows our clients to integrate with confidence. Each service’s operations have fixed schemas that remain intact through the lifetime of the operation. This provides the benefit of never having to scramble to implement, test, and deploy updates when improvements are made to our web services. Despite the schema rigidity, the support for HTTP GET/POST/SOAP protocols and the XML and JSON output formats allows for integrations using every modern programming language.
Now, let’s discuss the RESTful design principles. The REpresentational State Transfer style architecture has become the de facto standard for how stateless web APIs or web services are designed. The REST principles and constraints help to create a homogenous integration experience. However, some of the principles defined in this architecture do not apply to the Service Objects web services. It is important to remember that there is no official standard for RESTful APIs, and the implementation of specific features may differ from API to API.
The most common misconception we encounter is how our web services approach HTTP codes. Often in a RESTful API, the HTTP status code will provide information about the validity of a response: for example, HTTP 200 = OK, HTTP 204 = No Content, and HTTP 405 = Method Not Allowed. When doing data validations, it is easy to misconstrue the meaning of these HTTP codes. An HTTP 200 does not imply that an address, email, or phone was valid.
The proper way to interpret the result is to:
- Check if an HTTP 200 was returned
- Check if the response object has an Error object inside
- If there was an Error, handle the error based on the service specific developer guide
- Otherwise, a service specific validation was successfully performed. In this scenario it is important to review the service’s output fields to determine which scores/notes/warnings/etc. are important to your business logic
Example:
Service: DOTS Address Validation 3
Operation: GetBestMatches
Inputs: Address components and LicenseKey
Output (HTTP 200):
Addresses: [{
Address1: string,
Address2: string,
City: string,
…
DPV: string,
DPVDesc: string
}],
Error: {
Type: string,
TypeCode: string,
Desc: string,
DescCode: string
}
After verifying that an HTTP 200 was returned, your next step is to determine if there was an Error or an Address response. In the case of an Error your business logic should be built around the AV3 Error table:
https://docs.serviceobjects.com/display/devguide/AV3+-+Errors
If the response didn’t include an Error, you can dig into the Addresses array. In this example the validated address information is returned along with important Delivery Point Validation (DPV) scores. For Address Validation 3, the fact that an Error object wasn’t returned isn’t enough to imply that your results were valid. We recommend that you spend time in your service-specific Developer Guide to fully understand their validity indicators. For AV3, for example, you would look at the DPV score to determine if the address was valid, invalid, or missing some critical delivery information.
The concepts and workflows described above apply to all of our web services: Check for HTTP 200 → Check for Error object → Use service-specific response fields in your business logic. Once you understand how to work with a single service, the rest will become trivially easy.
If you would like to see our APIs in action, you can always grab a trial key from the Developers section on our products pages and download respective Sample Code to help you get a jump start.
