Posts Tagged ‘developer guide’

Swagger/Open API Added to Developer’s Guides

If you have poked around our Developer’s Guides recently, you may have noticed some changes and upgrades. We have introduced some stylistic changes that make these guides easier on the eye, but we’re also really excited about some changes that make it a breeze for developers to get up and running with our APIs and become their own data validation experts in no time! Specifically, we have integrated an Open API/Swagger specification form directly into these Developer’s Guides.

Open API/Swagger

If you are not familiar with Open API/Swagger, you should be! Open API provides a standardized framework that allows API developers to describe and outline the behavior of their API in a machine-readable way. From this description, Open API can then provide a user interface that allows other developers to quickly and efficiently determine how an API is expected to perform. It even allows users to quickly test example inputs to the API to see how it responds.

This user interface and the information it offers allows developers to easily and quickly integrate our APIs into their applications. This enables developers to have our APIs up and running in their applications in no time.

‘Try the API’ and ‘Service Reference’

Each of our Developer’s Guides will have two new nested pages. The one with the title “Try The API” will have our recommended operation for each service, and the “Service Reference” page will list all of the operations and methods available for each service. For 99% of use cases, we recommend using the operation listed in the “Try The API” page, as it generally meets the needs of our customers’ most common scenarios.

However, depending on the service used, there may be cases where other operations may suit your needs better. This is where the Service Reference page comes into play, with a list of the additional operations available for the service you are interested in.

Check out examples of both on our Address Validation – US Developer Guide:

Try the API:
https://docs.serviceobjects.com/display/devguide/AV3+-+Try+The+API

Service Reference:
https://docs.serviceobjects.com/display/devguide/AV3+-+Service+Reference

Note: If you don’t see these pages in your service of choice, don’t worry: we are rolling out updates to Developer’s Guide pages daily. And if you need something right away, please contact us and we can create something for you quickly.

No image, text reads Service Objects Tutorials

Check Out Our Updated Developer Guides

We recently revamped our developer guides to make them more user-friendly. The information for each service has been broken into its component parts, to make each feature more comprehensible. In this article, we share some of the changes we have made and they help you get the most from our products.

1. A new, easy-to-navigate landing page

Our new landing pages now have a developer guide map (our US Address Validation product is a good example) to provide easy access to each web service’s component parts. By clicking on the links on this page, you will be taken directly to the respective page that provides a more in-depth breakdown of the service’s individual fields. Below is an example of one of these landing pages.

2. Quick lookup & Open API

Our quick lookup page has been greatly simplified to provide only the most relevant data at your fingertips. Once you have received a trial or production license key, the validation process is as simple as plugging your input data into the fields, adding your license key, and clicking Execute. The web service request is made for you and the response formatted in the output section.

Similarly, if you are looking to run a different operation the Service Reference page has quick lookups for every operation within its respective service.  Check out an example of Address Validation US.

3. Citations and Additional Field Information

Have questions about the service fields? Need more information about how to leverage them to fit your business needs? Our redesign now includes accordion panels that can be expanded to provide more information about the field. We’ve also added citations next to some of the inputs and outputs where we have additional information available. In the example, below the Barcode Digits is linked to the following blog:

https://www.serviceobjects.com/blog/address-deduplication-using-usps-barcodes/

By clicking a reference link, you can read a more in-depth analysis of the field and often gain ideas about how to use the data point in your workflow.

Each of these new features is designed to help you get up and running more quickly with our services, and serve as an easy-to-use reference for your development work. Try out our new developer guide soon, and let us know what you think!