Hm. I mean I’m going through it now and it seems to make sense? It has a list of what is available, shows payloads and responses and links out to other documentation when it makes sense (like for subscribe_trigger). For a lot of the things its not really possible for the doc to detail out all the options. Like for call_service, it shows how to make a service call but what services exist depends on what integrations you hvae loaded so it can’t detail out all those options.
Tbh I don’t think I’ve ever seen really good documentation for a WS API. Thanks to Swagger and OpenAPI I’ve seen lots of great documentation for REST APIs since they basically set the minimum standard bar pretty high in that space. But I’m not really aware of a similar tool/standard for WS APIs, seems to be more of the wild west.
If you have a suggestion for improving this and/or can link to great WS API doc you’ve seen please open a Feature Requests with that. There’s definitely room for improvement here but its tough to design a system from scratch. Seeing other well-designed ones would really help.
I personally don’t work with webdev professionally, so I don’t have any WS documentation examples. I’m used to things like MSDN and ADN, which obviously set an extremely high bar that is pretty much unreachable for an OS project. But also open source developer documentation like for example Boost Asio. Their developer docs are light years ahead of that code dump on the HA WS API docs.
But anyway, it’s not really the technical docs in HA, or the lack thereof, that bothers me. It’s a bit annoying, but you can work around this. Worst case, I dig into the HA source to see how the API is implemented.
No, the problem is what you just said earlier: that the docs double as a registry to know whether an API call / endpoint is external and ‘supported’ or internal and subject to random changes. That’s a pretty vital information to know as a developer…
So the WS docs above were not updated since February. Does that mean that any changes to the WS API since (if any) are considered internal ? Or does it mean that simply noone bothered updating the docs ? And with the very loose approach to documentation in HA, how can you be sure of this?
Above, petro basically said that any custom frontend or conponent is to be considered using internal APIs. This directly contradicts what you said about documented API calls being external and safe to use. In the end, the main question I really have is - do you guys (you as in the HA core devs) actually want custom components in HA ? The more I dig into this, the more I get the feeling that the answer is no. You can’t keep people from doing it, but you’d rather not have to deal with custom stuff at all. Am I really far of with this impression ?
I was generalizing. I don’t dev for the frontend and I don’t know what API it uses. Last I looked, it didn’t use WS it looked like it used something else. Then again, I don’t dev in the frontend and the flow didn’t make sense to me so I was probably looking in the wrong spots. Sorry if that threw you off the path.
I can speak for the backend though (Custom Integrations). That API changes with every release, new things are added and old things are removed. It’s like any internal API.
It’s not a want/don’t want situation. No one really cares if you make anything custom for HA. But HA developers do not want to spend extra time ensuring that your code will continue to work. They want to ensure the core continues to work. The API deprecation warning serve 2 purposes. To notify custom “item” creators that things have changes and ensure things work for core integrations that do not have sufficient tests.
HA has had a firm stance that custom means ‘your responsibility’ and you have to adapt to them.
I had to roll back, because the custom Somfy Tahoma integration stopped to work and the Overkiz implementation in Core still doesn’t support the same level of functionality.
without partaking in this important exchange of views: I still wonder what brought about the warning.
In the returned text, not a single integration is mentioned, so in all honesty, I still don’t know what is going on and which part of HA needs fixing. Is it core, is it a Custom integration?
Seems I can now control my neighbors lights, and they are not even very near. Not only does this invade privacy in a 100% unguarded way, and makes us rely on ‘common courtesy’. it also brings about huge security risk, if this would go beyond the toothbrush and led lights we now laugh about.
I honestly feel this is yet uncovered in our security policy/guidelines, and we need to rethink that. Soon. We need to raise awareness on the matter quickly, because, where does this end?
Ive invested in some Temp sensors myself, for the fun of testing the Bluetooth proxy options. But I guess that will now stop, and I’ll return to Zwave sensors, which might be more expensive, but at least aren’t this easy to break into…
Sure I can click Ignore on this item, but what if my neighbors dont do that on my devices…
Don’t buy ble. That’s how they work. They don’t have security built in. There’s nothing that can be done, it’s how the devices behave. I’m not sure what you expect anyone to do.
That is unfortunately how many of these wireless devices work… in my neighbourhood (new build) I can see (and control) all heat recovery units, their remote controls and their CO2 sensors. They use an unencrypted RF protocol.
And all inverters have WiFi-dongles which run an open network with predictable passwords on them…
they dont offer local control (my neighbor can control the devices too), nor privacy first (same neighbor) al all!
tbh, with my first neighbor more than 40 meters away, I too am surprised I can see these devices. What’s with the old 10 meter line of sight for Bluetooth…
It’s all “security through obscurity”. These protocols were created >30 years ago, when the world was a different place. New devices are still built with it.
Unfortunately that kind of security doesn’t work when people put in the effort to decode these protocols because they want to monitor and control their own devices, coupled with the ability to create relatively cheap hardware as a hobbyist.
Not talking about these Bluetooth devices by the way, that is even an open standard…
Being able to control other peoples devices “just like that” without giving the owner of those devices the opportunity to secure their devices/network can already being called criminal. Petro’s post just made me aware that BLE is in fact “no-security by design”. (we have no BLE devices around, neither our neighbours)
But is reverse engineering a protocol a legal thing to do? I believe it is in the EU, for interoperability reasons. Not sure about the rest of the world.
