As a child I loved Lego. And when I say "as a child", I really mean "I still love Lego, but don't want to admit it". Recently a large new shopping complex opened not far from where I live, bringing with it a new Lego shop. In the centre of the shop are large perspex bins containing all the requisite parts to construct your own, bespoke "minifig" (or as non Lego fans might prefer "Lego people"). There's an hour of my life that I'm not going to get back.

Of course, one of the most satisfying parts of building with Lego is the interoperability of the parts, the way they snap together with a real feeling of rigidity. You can mix and match parts from different kits to create your own designs whenever inspiration takes you. I do wonder whether if that's why I took to being a developer with great enthuiasm.

A few weeks ago, before the London weather decided to bring us a year's rainfall in less than a week, I spent a sunny weekday lunchtime catching up with an old colleague. Before long, conversation turned -- as it generally does with nerds -- to development. One thing that came up in that discussion stuck with me: "I wish people would remember that APIs are not Lego."

Software vendors are very fond of APIs. So fond that they often see the mere existence of an API in their product as a fait accompli in and of itself. However, what this really means in practical terms is, "We're giving you a way of making our product work with others you might already own employing code you'll to have to build and maintain yourself. Oh, and it's going to be pretty-much proprietary. Maybe you'd like to buy some training?"

Not only are APIs certainly not like Lego, they are not equal. Talk to a developer and you'll find out pretty quickly that they range from the well-formed and functional to the fiendishly complex and arcane. Then ask about the documentation. Then probably buy them a beer to recover from having to relive personal nightmares.

The chances are that every piece of software you purchase is going to have to work with a range of others that you already own. Unlike Lego, they won't snap together simply. You'll have to tease them in place via an integration.

The good news is that you probably know well in advance how you like this to work at a business process level -- e.g., content from System A should be sent to System B under circumstances XYZ --- long before you start any purchase cycle. This should become one of your test scenarios that you can subsequently use to help decide which supplier offers the best  technical fit. (Vendor fit is another thing.)

So when you ask "How?" and a prospective supplier answers with, "...via our extensive range of APIs," be sure to request documentation to illustrate their answer. And then validate with developers or with your systems integrator. 

Whilst accidentally treading on a Lego brick in bare feet is one of life's more painful experiences, relying on an unknown and untested API to meet a critical need to your business can bring about much more lasting pain...