APIs are both a bridge and battlefield in the IoT era

Application programming interfaces, or APIs, have become the currency of the digital era. They are the link between devices, web sites, and services and as such, can have an outsized effect on your user experience. As a case in point, consider my frustration with Google Home and its inability to play the music I want well.

A friend at Google who looked into this for me said that my lackluster experience was likely due to a poor integration of the Spotify API with the Google Home. So after hearing APIs be blamed for frustrations in my personal life while also hearing people in various industrial or commercial settings talk about their challenges working with APIs, I decided to figure out what the heck is happening in this weird world of application programming interfaces.

First up, APIs tend to get all the blame, even if the problem is somewhere else in a device or in the back-end cloud. Blaming an API is the ultimate in shooting the messenger, except when it isn’t. Because sometimes APIs are the problem. Back when APIs became popular in the web world, roughly 20 years ago, developers used them to share information between web sites. That expanded to include computing elements, such as those offered by Amazon Web Services. And now, they are expanding again – to connect devices to web sites and to computing services.

But while the web world has had years to work out the kinks when it comes to developing APIs, the hardware folks are relatively new to this. Kin Lane, a consultant who goes by the title API Evangelist, says the folks developing APIs for devices tend to break some of the API best practices because they aren’t thinking about how others – especially non-hardware experts – might use them.

One of the most common API usability crimes hardware folks commit is using jargon or inexplicable acronyms to describe the access they give and functions they offer. If you’re making an API to connect to a light bulb, for example, labeling parts of the API with a cryptic color value may not be as handy as labeling it blue or yellow-white light. Consider as well how it will be used, and for how long. An API has the potential to become infrastructure, which means others’ services or businesses may rely on it. If that’s the case, you should communicate with them when you change something, ideally before you change it. And you shouldn’t change it every few days, because it’s likely the developer in charge of handling your API is also in charge of many others.

Another API design sin is putting too much complexity into it. Prakash Khot, CTO at AthenaHealth, says that keeping things to a minimum and designing for modularity helps keep an API stable and usable. He also recommends that you consider error messages and feedback as part of the overall API design.

Too often when a request fails, the API designer hasn’t created a way to communicate what went wrong. This is frustrating for the end user and the company trying to work with the API. Also, in the case of an error message, Khot recommends thinking about the user’s privacy. For example, if a credit card number isn’t shared properly, don’t ship the number back and forth as part of the error.

Outside of basic design considerations, any business that wants to build an API (and really, that’s going to be every business in the IoT economy) should consider two other aspects. The first is politics and the second is business goals. When companies play politics is where end users might see the most frustration. An example would when Google decides to promote its own music service over that of Spotify on its Home device by using a subpar integration. It might also show up in cases where a competitor’s device can’t even access an API, or has rate limits that mean it’s going to perform more slowly or time out often. I anticipate this kind of API warfare between Nest and Amazon in the near future if they don’t patch up their spat. This may end up in one of the businesses filing a lawsuit against another business, which is common in the business world but is resolvable with a competent lawyer.

When it comes to business goals, consideration can start with the information that you provide as part of your API, but might also be as direct as charging for access to an API or even paying others to use it. API calls do cost companies money since they have to provide servers to support information requests and developers to keep them up and running. However, they can also perform an invaluable scouting function for a company. For example, a company like Philips can see what cool things developers are doing with its lights if it looks at API data. It may then decide to buy a particular startup or hire a particular type of engineer.

Though I’ve dug deeper into the world of APIs, I still haven’t figured out why some of my individual devices behave so strangely. But I feel like I have discovered where the future of business contracts – and disputes – will be held in the new era of the internet of things. I can’t wait to learn more.