APIs for IoT: What Matters

There will be 1 trillion connected devices by 2025 — connected to each other, to the Web, to us. All of the companies jumping into this space, as well as the ones who’ve been here awhile already, are exploring new ways to enable this connectivity. It’s a ripe open playing field and a very exciting space, with a lot of innovation to come. In the future of these networked devices, more typically device-oriented protocols like CoAP or MQTT may influence or completely change how or if we use HTTP as part of process of getting and sharing data from these devices. Development in WebSockets, distributed systems, and other big data and network technology is already changing the way we work with IoT, APIs, and the Web.

For those of us building now, and shipping IoT devices and platforms out the door, we have a decision to make: How do we build our APIs for maximum accessibility, flexibility, and scalability? Especially with the completely new territory ahead of us, with all of its challenges, opportunities, and uncertainty, it can be easy to get caught up in the myriad of trending technologies or feel like the sand is shifting too quickly beneath your feet.

When it comes to building an API for your IoT device or platform, whatever technology or stack you decide to use, there are three traits you should keep at the forefront of your API’s design and implementation:

 These devices don’t exist just when we turn on our phone or open our laptop — they are part of our daily life. Missed messages from your car could mean more than an annoyed boyfriend or being late to pick up your child. API developers for the Internet of Things have a responsibility for making their APIs reliable — and developers using those APIs do too.

Data redundancy, persistent message queuing, and other preventative measures against message and connection failure are a must, but what happens when something does go wrong? In-depth logging not only helps you identify failures, but when made accessible in your developer portal, can be invaluable for your developers to identify when and why messages (such as HTTP requests from webhooks) fail.

 The things we care about from our devices tend to be event-based, and the events matter when they happen, not minutes or hours after they happen. When your phone enters a certain radius of your home, your Nest should turn on. When a door opens when you’re not home, your Notion sensor should alert you — or tell your connected light bulbs to flash red.

At Notion, we’ve decided to use webhooks to enable real-time connectivity — in the above example, when the sensor detects the door opening and you’re not home, we’ll send a request with that information to other applications that may be waiting for that event. You could also use one of the growing number of companies offering push services to help you achieve real-time synchronization with third party apps, but obviously third-party services come with a cost. Another option is to integrate WebSockets into your API or dev tools — although not as replacement for a RESTful API — which might be a good choice if you need to offer longer connections or support more frequent or simultaneous and bi-directional data flow, which we currently don’t.

 This is probably the most important factor to keep in mind when building an API for connected devices. It may seem obvious, but connected devices are even more useful to us when they can connect to each other. What does this mean for an API?

First, it involves a lot of research about the APIs you want your IoT device or platform to be able to integrate with. Find out if other companies require certain authentication protocols, or if their APIs even allow the sort of integration you’re imagining.

Your research isn’t just reading docs and talking to the other companies — it also involves actually trying to build programs integrating your API with other APIs. With a hands-on approach, you’ll start to learn what endpoints and data structures are most useful for integrations.

As important as research — and this is true for any API in any industry — is documentation. Put time into good tutorials and code examples demonstrating integrations, and even code libraries helping make integration easier. Your goal should be to enable developers to get integrations with your API working in minutes.

This is what we’ve found from building our API, we’d love to hear what you’ve learned from building yours.

If you found this article helpful, we can send you emails when we post new stuff:

Originally published at Notion Blog.