API Design Considerations for The Internet of Things

Since the Application Programming Interface, or API, is the circular system running throughout the Internet of Things, you could ask how API design is affecting IoT. Given the constraints inherent to IoT and the potential of its impact, you could also ask how IoT is affecting API design. Whether the market or even the developer community is ready, this Internet of everything is set to reach $19 trillion in the next decade — yes, trillion — and, according to Cisco, will leave a dinosauric imprint on our society much broader and deeper than the Internet itself did.

As an API designer, you’d be crazy to not get in on this craze. This piece goes into how to create effective API design in the IoT space.

What Exactly Is the Internet of Things?

We spend a lot of time talking about how APIs connect offline items online, but, like most things involving the Internet, at least one piece of the puzzle is the connected human.

“Ultimately, if we see how people will use the Internet of Things, that’s probably where that will end up, where products will come which actually will have a commercial potential that kind of loop into this humanness about touch and seeing and presence,” said APIcon UK speaker Holger Reinhardt, founder of launchd.io, former member of API Academy, and now CTO of Haufe Group.

Besides being a connector of things, the definition of IoT is still quite broad, leading to a lack of agreement, particularly between protocols.

As Reinhardt said, “There are people talking about IoT and there are people looking for IoT and the only thing they can agree on is that it’s called IoT, but beyond that, Cisco talks about something which is completely different from what GE talks about. IoT is just this wonderful canvas that everyone can project their imagination and their dreams on, but you will be hard-pressed to find really what IoT is.”

API designers who are working within the IoT space will surely shape that meaning for the future.

How Will the Internet of Things Shape API Design?

As we’ve already talked about, effective API design is all about business strategy and objectives. APIs are simply a means to an end. While people may want a certain result that an API is capable of providing, they are most often searching for a solution, not necessarily the API itself. Your API has to have a compelling enough purpose for someone — most often a developer first and then the end consumer — to use. According to founder of API Science John Musser, a well-designed API is simple, flexible and easily adopted.

Manfred Bortenschlager, API market development director at 3scale, aptly pointed out that the simplicity and flexibility of API design is inherently linked to the context in which it’s used. As with all relative constructs, these depend on the use case. He recommends keeping simplicity in mind when considering the following aspects of API design:

  1. Data format: As Reinhardt said, look for what the developers would like to use; "if they’re using JavaScript and JSON, don’t give them a Web Service API."
  2. Method structure: Are the methods generic or specific to targeted requests? What is the usual sequence?
  3. Data model: The underlying data model can strongly impact usability and maintainability.
  4. Authentication: This is dependent on need and context.
  5. Usage policies: Everything must be really easy to understand and work with.

These best practices certainly carry over to the APIs for the IoT.

Be sure to read the next API Design article: Why It’s OK To Design Imperfect APIs