An API - is it worth it?

Firstly, lets clear up what we mean by an API or Application Programming Interface to use the proper name.

An API is a set of methods designed and developed for third parties to interact with an application. It contains documented methods and usually takes the format of GET or POST HTTP calls which result in HTTP responses.

An API sits between a user and the application... it protects the application as no security information such as database connections, table names and field names are revealed. It is simplified process where a user asks for a bit of information and by return they are sent that information.

Twitter has an API and so does Google, Facebook and Flickr... but these are BIG companies. Why would you need one? Well not everyone does. Until recently here at GeekyCreative we had used API's but never written one. Then a client asked us to integrate their website with a custom built telephone system. The telephones play recorded messages specific to the users request and this all needed to tie into a website that was built by another developer. So.... we have a situation where two developments need to talk to each other - this is exactly the situation where an API is useful.

GeekyCreative were initially asked to consult on the issue and after talking to the parties concerned it was decided that we would be best placed to write an API.

Now, we could have written a set of scripts that we specific to the telephone system currently in place, but, we looked forward at scalability and decided that there were two many potential problems with this rigid approach. For example, an upgrade to the telephone system could mean an update to the API. The same could be true if the website where updated. If you wanted to integrate someone new then you would often need new scripts to accommodate them.



However an API sits between the two, so as long as the database structure remains the same and the inherent functionality is not changed then the API is always current.

Let's face it... if you change your database structure post development then there must be a very good reason for this and therefore you would need to revisit your API anyway. Having a layer of code between third parties and your application means that you can be more flexible and yet still maintain control - changes to API code files will not directly affect your website. How users call the API and deal with the responses is up to them. So an API removes some development burden as well. By dictating how the information needs to be requested, what information is available and how that information is returned means that as a client you have very strict control.

With an API you also have a quick and easy way for new suppliers to use you application or website - should other users want the information they can look over the documentation and make their own API calls. Which brings us to the most important part of an API, the documentation.

For our first API we built a little microsite which documented all of the methods, variables and responses. It also contained an AJAX test area where users could construct a call and test the response on screen. This sped up the development time no end and will remain in place for future use. We wish that we could give you the link but at the moment this is a closed development and we must keep it so.

The screenshots show the level of detail that we went into and we are pleased to say that the system is now live and working well for www.debraballhomes.co.uk - check out the site and if you find time phone up to hear an audio description of a property. The description you will hear is generated by an API.