developers.home-assistant icon indicating copy to clipboard operation
developers.home-assistant copied to clipboard

Published 20 hours ago • verified publisher icon home-assistant

Add warning that REST API is no longer supported

Open iamjackg opened this issue 10 months ago • 5 comments

Proposed change

According to https://github.com/home-assistant/architecture/discussions/1074#discussioncomment-9196867 the REST API has been superseded by the WebSocket API. There was no mention of this anywhere in the documentation, so I'm adding a warning to let people know.

Type of change

  • [x] Document existing features within Home Assistant
  • [ ] Document new or changing features which there is an existing pull request elsewhere
  • [ ] Spelling or grammatical corrections, or rewording for improved clarity
  • [ ] Changes to the backend of this documentation
  • [ ] Removed stale or deprecated documentation

Additional information

  • This PR fixes or closes issue: fixes https://github.com/home-assistant/core/issues/99820
  • Link to relevant existing code or pull request: https://github.com/home-assistant/architecture/discussions/1045

iamjackg avatar Apr 23 '24 12:04 iamjackg

This really needs to be merged so people don't rely on the REST API for new projects and then get burned...not that I would know anything about that! 🙃

In addition, I don't remember seeing any mention of this on the blog. Has there been a post about it?

Klikini avatar Apr 25 '24 04:04 Klikini

Deprecating the REST API is a really bad idea and will put a stop to projects based on cheap hardware (esp32, etc.). Calling the websocket API on such hardware is unnecessarily complicated. Very disappointed with Home Assistant and this "surprise" depreciation (ping @emontnemery). Thank you anyway @iamjackg for your PR.

sebsebseb1982 avatar Apr 25 '24 07:04 sebsebseb1982

@sebsebseb1982 I learned today that getting states with the Websocket API is actually impossible on memory-limited platforms like those.

I thought there would be a command message to ask the server for the state of a single entity or list of entities, but no, you can only request the state of all entities. This array would take up more memory than embedded devices have, and iterating over an array of a thousand or more entities would take forever even if it fits.

I would really appreciate some justification from Home Assistant leadership as to why the REST API is being ~deprecated~ superseded by the WS API, and an opportunity for the community to provide feedback on that decision that will negatively impact it.

Klikini avatar Apr 25 '24 07:04 Klikini

Thank you @Klikini for this warning. I would have been very upset if I had also wasted my time using the WS API without it being viable.

sebsebseb1982 avatar Apr 25 '24 08:04 sebsebseb1982

I just ran into issue home-assistant/core#99820 and spent over an hour banging my head against the wall trying to figure out why it wasn't working.

That is frustrating to say the least.

I agree it seems like the REST API is EOL, will no longer have features added, or at least the get_forecasts will never be supported in REST.

Since at least one of those statements is true, can we at least get a more clear error message to help others who wind up here?

krkeegan avatar May 01 '24 22:05 krkeegan

closing this PR per https://github.com/home-assistant/developers.home-assistant/pull/2150#pullrequestreview-2017433583

bdraco avatar May 20 '24 02:05 bdraco