What makes an API great?
APR
22
Apr 22, 2013
by
0
We have been doing some work with shipping services API from multiple providers. Integrating various API's over the years we have worked with a variety of technologies and have seen first hand the pitfalls in some of the implementations.
So what makes a great API? There are a few crucial factors that make an API easy to integrate and reliable.
- Good API documentation
One of the well known shipping providers in the United States, the US Postal Service, has a XML API available for their customers to integrate with to generate tracking information and a shipping label for use on their package. In implementing this API we discovered that their documentation did not match the implementation. There were crucial bits of information missing from the documentation. - Cross platform compatible technologies
Everyone by now has heard of XML; pretty much all programming languages have facilities to process and parse XML. There are other great cross platform technologies such as JSON which has gained popularity. Using a cross platform compatible format is necessary for wide adoption of the API. An example of a non-cross platform compatible technology would be Adobe flash, or ActiveX. - Version change isolation and developer notifications
From time to time an API may need to be updated to support a new feature or business process. Sometimes these updates will break current implementations of the API, meaning that everyone who has implemented that API into their programming will have to make an update to how they query the API. Great API's will try to isolate these changes and create a new version number, keeping the old version around and working until developers have had a chance to upgrade. They will then send out notifications to their integration partners/developers that a new version of the API has been released and the old version is deprecated and will be deactivated on X date. The US Postal service API tends to not notify their developers and not keep versions of the API isolated, so from time to time the calls made to their API will simply stop working, and developers must then troubleshoot as quickly as possible to identify changes and make updates to their programming.
Leave a comment
To leave a comment, please log in / sign up
RSS Feed
Facebook
Twitter
LinkedIn
YouTube