Why It Is Important to Build Long-Lasting APIs: IoT Perspective

29 July 2017 |

iot

A few days ago, I decided to watch a couple of API-related videos on youtube, and then the topic went IoT (Internet of Things) and IoT APIs. That was when I came across “The internet of things challenge: building APIs that last for decades”, a recorded presentation by Irakli Nadareishvili, the Director of Strategy at CA Technologies. The speech turned out to be so good that I could not help sharing the beautiful ideas with you.

According to Irakli Nadareishvili, the main IoT challenge we have today is building APIs that would last for decades. The whole speech itself is dedicated to explaining why it is important to build long-lasting APIs. It would be too silly to give out the answer right away without proper explanations, and, fortunately, this is not the case.

Why IoT perspective?

Go out and turn around. Though what you will see is not that much surprising, the facts, on the contrary, are way more astounding. In his presentation, Irakli Nadareishvili mentions that 80 devices are connecting to the Internet every second today. The number is going to rise up to 250 till 2020. This literally means 50 billion connected devices or 7 gadgets per person on average! Still not flabbergasted?

We are on the edge of massive changes because IoT is going to weave into our lives and reshape them greatly. How we live and connect to the environment, and, what is more important, how the environment connects to us, are going to be different. And a completely different life requires new approaches to writing software. If nearly everything is connected to or driven by APIs, only one mistake can cause billions of breakdowns. Hence, it is important to build lasting APIs, the fewer versions, the better.

Where do we get inspiration?

The Internet is the largest and most distributed system that has been around for 25 years. It is enduring and resilient. It is the perfect example of what an ideal API should be like.

What about its architecture makes it last for such a long time?

Not surprisingly enough, it is hypermedia. The Internet is nothing else than billions of interacting documents. Imagine if we had something like that and it would last for 25 years. Is HTML the secret ingredient? No. Once again, it is hypermedia.

Irakli Nadareishvili believes that the main woe of not building hypermedia APIs is coupling (“the biggest toxic thing in this environment”). What we have now is APIs responding to just data. The perfect response would involve both data and metadata.

Here we should mention affordances or “all “action possibilities” latent in the environment” as James J. Gibson once defined it. In other words, a thing tells what you can do with it, and all the affordances come to you right after you have recognized the object. You need no manual to realize what actions to perform upon a chair, for instance. Object + affordance = useful object. Unfortunately, this is not how we build APIs today.

Familiarities are also talked about by the author of the presentation. He exemplifies them as a van and a sports car. They are pretty not the same, but we know how cars work in general. There is no need for a manual. Here Irakli Nadareishvili shares some of his driving experience, “By knowing how to drive a small car, I knew how to drive a truck”. Why? Because they have the same affordances.

This can be applied to APIs. All Application Programming Interfaces have something in common, but still we read manuals to know how to work with them. Think about HTML and browsers. We do not create separate browsers for every new website. Any of them can run any web page. You could object to this and say something like, “But wait, browsers have humans with brains and intellect and artificial intelligence cannot differentiate a cat from a dog.” And right you are.

The written above leads to mentioning the problem of semantic gap (we need a specific understanding of an API). We can communicate one API with another, but as soon as we enter the issue of industry knowledge, the need of a specific semantic understanding of the API arises. The solution lies in how the problem of artificial intelligence was solved everywhere else. Smartphones are where it is hidden. They have a limited vocabulary they understand, and then while interacting with the user they try to learn more and expand their vocabulary.

We can do the same thing, that is, create a vocabulary for specific industries and applications. The speaker notes that there is already an RFC 6906 standard dedicated to this, and it is called “Profiles”. He also provides such profiles examples as XMDP (HTML-only), PMP (CDoc-only), and ALPS.

Any website is a perfect hypermedia system because it provides both content and control (links you can click, forms to submit, and metadata to interact with the information). The issue is to do the same in APIs.

Many still do not write hypermedia APIs, as they are relatively new to the industry. Irakli Nadareishvili shares his experience of what to do when you are stuck when writing one. When such a trouble happens, he thinks, “What if it was a website?”. With this question in mind, you are going to make the right choice because you know how to build web applications and hypermedia is all about it.

The speech ends with examples of who uses hypermedia APIs (Github, Paypal, Microsoft Lync, etc.) and who to follow to find more information:

  • @mamund
  • @apiacademy
  • @darrel_miller
  • @jharmn
  • @kinlane
  • @inadarei

"The internet of things challange : building APIs that last for decades" by Irakli Nadareishvili