Updated from November, 2010.
One of the most important tools in my utility belt for troubleshooting, referencing, and integration is the “service path.”
The service path is basically a URL that takes you to a sort of “dashboard” for a service. You can use this dashboard to: test a service; see the XML request/response structure; review the operations that are available to you, and a slew of other useful information. You can find the Service Path for any product on the product detail page, or in the Dev Guide.
Here are few valuable pieces of information that you can get from the service path.
View all available operations for a web service
We’ll use Address Validation US as an example. Let’s go to its service path: DOTS Address Validation – US 3 To run a transaction, you’ll need to use your existing Address Validation trial or production key, or get one here. Without a key, you won’t be able to run a test, but you’ll still be able to see operations and their respective inputs and outputs, etc. (Please note: Trial and production keys are product-specific. To run a test on another product, you will need to secure a key for that product. Please click here for a complete section.)
Run a quick transaction against an operation
Once at the service path, click on an operation, place values in the textboxes, and click “Invoke”. The service will return a response in raw XML format. This is what your application sees before it parses the data.
View all required inputs for an operation
Click on an operation and note the input fields on the form that appears. For example, “ValidateAddressWithDPV” expects Address, Address2, City, State, PostalCode, and LicenseKey as input fields. All of these fields must be sent to our service (even if they are sent without any data) for it to accept the request.
View all possible outputs for an operation
Scroll down past the form and look for “ValidateAddressWithDPV” and click on “GET”. The 2nd shaded box will show you the list of XML outputs that our service returns on a successful transaction. For example, and are both possible outputs for ValidateAddressWithDPV.
See what the output will look like in XML or JSON
Go to the operation page, and either run a transaction (which will output the raw XML in a browser window by default), or scroll down to the operation name and click on the protocol you will be using (“GET” for example). You will see a shaded box showing the XML that will be returned to you. Scrolling further down will show you the JSON output. Note: you can also view the JSON in your browser request by changing “format=xml” to “format=json” directly in the URL.
View the WSDL
Go to the main service path URL for your specific DOTS Web Service and click “Service Description”. For example, go here and click on “Service Description” (located in the first line above the operations). The Web Services Definition Language, or WSDL (pronounced Whizz-dull) describes all these operations, inputs, operation descriptors, data types, etc. In fact, all the service path pages you see were generated from the WSDL. If you use a language that requires a WSDL URL, then it likely is generating entire objects from that document and handling all the request and response structures for you.
So there you have it! I hope you get to add this to your utility belt too. It’s an invaluable tool that I use on a daily basis.
