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.
