Why Home Assistant doesn't have an external API for integrations

Home Assistant is the world’s largest home automation platform talking with over 1700 different devices and services. Home Assistant works with these via “integrations”.

Each integration runs inside Home Assistant. They convert the data from the device into data that Home Assistant understands and forward commands from Home Assistant back to the device. For this to work a device or service needs to have an application programming interface (API).

It is not possible for a device or service to provide lights, switches or other device types via the Home Assistant API without an integration. It can be faked, but it won’t work correctly. We explicitly did not add this feature because of interoperability.

If Home Assistant were to offer this option, devices and services would no longer be required to create an API for control – they could just implement ours. This creates vendor lock-in, locks other home automation platforms out and hurts the open Internet of Things ecosystem.

You should be able to access your data from your devices without any restrictions. Requiring a specific application to get to your data is not the solution.

Our goal is a home where all smart devices can be managed locally.

This stance will hurt us in the short term because we get less integrations. It is more work for a manufacturer to create an API and a Home Assistant integration.

In the long term the user will win. Devices with local APIs will still work 10 years from now and no one will be held hostage by vendor lock-in because some of their devices only work with Home Assistant.

Note about Home Assistant APIs: Home Assistant does have an API, just not for integrations. It allows you to access all your data in real-time. We also have a data science portal that documents how you can query the historical data stored on disk.


This is a companion discussion topic for the original entry at https://www.home-assistant.io/blog/2021/05/12/integrations-api/
12 Likes

I welcome this approach very much and hope that other company will join in. Especially also those that currently explicitly only focus on cloud access.

What if the API were based on MQTT?

Home Assistant’s existing MQTT Discovery isn’t ‘feature complete’ to constitute a full-fledged external API but it demonstrates the basic principle.

If every device’s integration communicated via MQTT, it would allow them to be used by any home automation system capable of acting as an MQTT client.

Many years ago, this degree of interoperability was the promise of open protocols like xAP. A device’s xAP integration could be used by any home automation system that supported xAP. However, it never gained wide adoption (nor did the similar xPL protocol).

MQTT is widely used (far more than xAP or xPL ever were) but doesn’t define the information’s structure. That’s what the Homie IoT convention attempts to address.

Given Home Assistant’s wide adoption, an external API based on MQTT and Homie, or something similar, perhaps even an enhanced version of MQTT Discovery, would not lock anyone in or out. In fact it would make the integrations available to a wider audience. Other benefits include decoupling Core from integrations; you could restart Core without forcing a restart of its integrations and each integration could be updated separately (closest existing example is Zigbee2MQTT).

However, I realize this involves a great deal of work; it’s a non-trivial challenge.

6 Likes

I think this is too much of “purist” PoV. If you are developing an open integration standard and open source SW, how exactly is my data going to be “locked”. If the standard is open I can always create my own implementation.
On contrary - by NOT providing “integration API” and data model the customers are suffering. From my experience most of the HA integrations are a bit hack-y and require manual tuning. By providing unified “integration API” you can help the small IOT developers implement only one interface and have 1st class automation system. The end user user is also winning as they will have well working, stable and consistent integrations. And let’s be hones even if you define an API, Tuya and Philips, etc. will never implement it as this is not their business model.
Nice statement but it sounds like avoiding responsibility.

6 Likes

Really excellent point. And now I have a bunch of other things to read about.

It’s pretty feature complete for the platforms it supports, no? There’s definitely integrations that do more then just create the listed types of devices. But clearly you can get pretty far this way. Zigbee2MQTT is a great example, as is ZwaveJS2MQTT and Room Assistant.

1 Like

What if you provide the esphome api as standalone one? It already has the api and the integration, and it is open source, isn’t it?

3 Likes

The flexibility of home assistant makes sense from your point of view. However by working on all those integrations it is likely that you have learnt a lot about good and bad designs as we as common issues many iot devices have. That API would be built based on all the lessons you’ve learnt and some IoT companies might benefit from your design decisions.

The IoT providers may (will!) eventually want to ask you to prepare integrations for them in their planning phase. Having a template or an API they could adopt may make things easier for them. If that happens, please be ready for them.

1 Like

I can’t argue with that statement; it does what it does for what it was designed to do. However, an external API needs to do more.

An external API needs to handle everything that can be currently modeled in Home Assistant. Compare the left hand list to what is displayed as supported by the MQTT integration here (i.e. what MQTT Discovery currently supports):

Search MQTT

If MQTT Discovery served as the basis for an Integration API, it would need to handle weather, text-to-speech, calendar, irrigation, etc. That’s why I said it wasn’t feature-complete.

1 Like

Agree, support protocols, mainly open ones and advertise open standards and devices that support it so that we users can buy those instead of some proprietary crap

2 Likes

At 1700+ integrations the hurt seems minimal so far :slight_smile:

I’d even say it’s the other way around.
I’d certainly never buy anything IoT that doesn’t at least have an API that would allow an integration to be created, so not providing one will hurt the “closed” vendors more…

2 Likes

I assume this came up to avoid things like this in the future?

While I can understand the move, especially in light of events such as the one discussed on the Reddit link above, a HA API would be open source by definition and could be adopted by other home automation systems if they so choose. It would just be yet another home automation API amongst the myriads of existing and mutually incompatible home automation APIs. Certainly not ideal, but hardly a vendor lock in.

But yeah, MQTT is awesome.

It really depends on how an “external integrations API” is implemented.

While MQTT is a protocol of its own, Home Assistant designed a pattern of MQTT topics and payloads to provide more functionality through MQTT. And due to the simplicity of that pattern as well as the popularity of the Home Assistant protocol, many external projects utilize Home Assistant’s topic and payload pattern to act as an “integration”. While this “integration” works with Home Assistant, it will work with anything that can consume these topic and payload patterns.

If Home Assistant designed a full featured integration API it would be open source and well documented. If it is designed correctly, there would be no vendor lock-in since any Home Automation Hub software would be free to implement that same protocol.

However, by not designing an external integrations API, Home Assistant requires device vendors to create yet ANOTHER protocol for their device, and then a Home Assistant integration still has to be written to allow that device to be integrated into Home Assistant.

By designing one, open, full-featured protocol, Home Assistant will be paving the way towards standardizing a Universal Home Automation Protocol allowing vendors to simultaneously provide open access to their devices and integrate with Home Assistant. Just like HomeKit without the “Apple Lock In”, or Amazon Alexa integration but without the cloud requirement.

Finally, the existence of such a protocol would help reduce the number of new devices on the market with “cloud only” protocols and, if all vendors moved to such a protocol, drastically reduce the amount of integration maintenance Home Assistant developers would spend their time on.

To be fair, nothing is stopping standard enthusiasts from creating an HA integration that implements whatever standard IoT/home automation API that catches on, WebThings or whatever. Home Assistant as a project indeed need not get involved in any of this.

Ho-o-o-o-owever!
What Home Assistant can do instead is recommend an already existing stable and well-documented API (if it exists?) for implementation by device manufacturers. This relieves the manufacturers of the necessity to produce anything HA-specific, and HA doesn’t get any new exclusive APIs.
Looks like a win-win, no?

Yes there is, it won’t be merged into core. Merging into core requires approval of the dev team and clearly by the above post that won’t be approved. Sure you can do it as a custom component but that’s kind of pointless in this case. The reason for doing something like this would be to make it easy for manufacturers to integrate with ha without knowing anything about ha. If manufacturers have to instruct users “download and install this custom python component into their ha” then that’s no longer easy and universal. Clearly they have to know a good bit about ha.

I’m pretty sure the reason for this stance and post is that a standardized api like that doesn’t exist. If there was an open standard for generic integration of devices and services with any home automation platform we wouldn’t be having this conversation. It’s happening because currently every automation platform does integration differently.

But if you know of one then make an adr. That would change the conversation significantly.

Correct me if i am wrong.

Isn’t the whole point that ‘your’ api should be open? Not the other way around?

The power of that turns in this case into major weakness. Enthusiasm is pretty temporary phenomenon.
It’s not enough to create the integration. It must be long-term maintained, following changes in HA as well as upgrades a manufacturer is doing do device/firmware.
Take Shelly as example.Obviously it’s one of most popular brand these days. Despite of super active developer (Maciek), there were lags in delivery of updates to match new features or even breaking changes. Those delays took weeks and even months to deliver making some devices unsupported for this time or forcing users to use older firmwares.

Nobody wants to end up with not functional devices in his home automation ecosystem waiting weeks for support renewal.

I already mentioned that an integration must be constantly worked on not only because of manufacturers who offer changes to their devices but due to changes (often breaking, unexpected ones) done to HA.
If you track recent 5 major releases of HA you obviously can see how many integrations are being stopped working. And how many times the answer from core devs (or rather core moderators) is: it’s not part of HA core, go complain to the integration developer.

This is why I decided to stick with mqtt as integration bridge with Shellies. It’s most reliable and basically doesn’t rely on anyone’s enthusiasm nor commitment nor free time nor will.
I can imagine such API, based on proven technology (like mqtt) would profit to all parties