Getting Ticked Off with APIs

We get to integrate with lots of APIs as part of the day job, usually by passing XML or JSON over HTTP but sometimes (less often thankfully) with SOAP or even sometimes using something zany like ActiveMQ.

The thing I find interesting is the API that is provided to the service consumer, i.e. me!

Some of these are really excellent and some are poor or non-existent. And some fall in-between.

In college I learned about object-orientated principles and I think some of them can be applied to APIs. Namely those of encapsulation and abstraction.

I find using a good API like using a function or service that adheres to good OO principles. I should not care how the API does things behind the scenes. I should not care how it represents data, how it stores it – I just want a result.

But I also want a simple way to pass data to the API. And this is what prompted me to write this post. I was integrating with an API recently – and I wanted to make a simple call to get all data between two dates. So the API call was something like:

getData(dateFrom, dateTo)

…which I would call as follows…

https://web.service.url/getData/?dateFrom=x&dateTo=y

This was all fine until I realised that the parameters to be passed needed to be expressed as .NET ticks. WHAT?!

I have nothing against .NET or how the platform represents time but I was pretty flabbergasted that the API writers expected me – on a ColdFusion language platform, or any other platform like Ruby or Python – to convert my dates to .NET ticks before I sent them on to the API.

Why?

• I have to care how the API writers represent time.
• I have to care about a language I don’t use.
• I have to pass language specific representations (ticks) to a web service, and web services are supposed to make system to system calls language agnostic.

I had no choice but to go off and find out how to convert a date in ColdFusion to .NET ticks. It took time, and it was completely unnecessary. I have no doubt that had the API writers put their minds to it, the web service could accept two dates in string format (e.g. YYYY-MM-DD) and work out the details for me. Dead simple.

I let the API writers know how they could improve things for other integrators in future.

By the way – if you need to know how to to convert a ColdFusion date/time to .NET ticks then check out this snippet.