SimonDickson.co.uk

Menu
 

A plea to API owners

‘API-first’ thinking has been around for quite some time now. It’s the notion that you shouldn’t think about building (for example) a website: you should think about building a data API, and then – as a separate thought process – building a consumption or presentation layer on top.

The theory goes that, if you get the data API right, then it’s easy to swap in a new front-end when you fancy a change. It may also allow you to share that data with another service, be it your own or – even better! – someone else’s.


I recently built a custom Alexa skill to address the defining user need of UK local government: which bin do I need to put out on which day? Courtesy of a contact at my local council, I discovered how to access the API which powers the council website. (They don’t offer it as a public service, but my reputation preceded me: in a good way, for once.)

It gave me the data I needed, but in a format which had clearly been conceived only to power the website. Dates didn’t include a year: just the day name, day number and month name. (So, Friday 1 January.)

It would no doubt be obvious to a website visitor, looking at the web page, which year was meant. But computers can’t infer that sort of thing: so, given that I had to sort by date, I had to write some additional logic to work out what the full year would be.

Easy enough. But frustratingly, the machine powering the API must have known the relevant year. I was writing extra code to extrapolate and restore data which could easily – in fact, probably more easily – have been included.


My Alexa skill worked fine for a number of months. Until this past week or two, when the API response changed. If a collection was today, its primary text response was now: Today.

That probably made for a better user experience for the website visitor: indeed, my Alexa skill did exactly that, in constructing the voice response. But my skill wasn’t expecting the change: and it broke. Again, the fix was pretty easy, as the date was being sent in another field; but it was another unnecessary interruption.


So my plea to API developers is as follows.

  • Think of the API as a stand-alone product… Assess its success in and of itself, rather than a means to another end. Make it as helpful, flexible and reliable as it can be. You’ll eventually find a reason to be glad you did.
  • … and think of yourself as Just Another Consumer of that API. Once the API launches, don’t do yourself any special favours.
  • Supply data in the most raw, standard, flexible form possible… In the case of dates, that might mean the number of (milli)seconds or days since 1-1-1970; or RFC 2822; or ISO 8601. They might not look pretty, but this isn’t about looking pretty: these are widely adopted standards, and virtually any modern computer and language can produce and work with them, without extra pre-processing. And even if they include elements which you don’t immediately need, someone else will.
  • … and do any tweaking in your consumption layer. By all means, change the date display to ‘Today’ – but do it in your web page, not in the API response.
  • Don’t change things once the API is out there… Developers, and the users of their apps, require reliability.
  • … but don’t be shy about extending it. If you decide you really need to format something slightly differently, maybe add a new line to the API response – keeping the old one as it was.

Most importantly though: please keep thinking API-first. It’s fantastic that any of this was possible in the first place. If we can get used to doing this in a developer-friendly fashion, it uncorks all kinds of possibilities, and rarely means extra work.