REST API: unnecessarily complicated and impractical

[TCB13]

Hello,

First, I want to express my gratitude for ESPHome and the incredible work done by all contributors. It’s a fantastic project that makes home automation highly accessible.

That said, the ESPHome REST API is poorly designed—it makes everything unnecessarily complicated and is impractical for real-world use.

For example, we can query the last known state of a specific sensor like this:

$ curl http://10.0.0.10/sensor/temperature
{"id":"sensor-temperature","value":17.87281,"state":"17.9 °C"}

This is great. However, how do I know what sensors are available? Why isn’t there an endpoint like this?

$ curl http://10.0.0.10/sensors
{
  "sensors": [
    {
      "id": "sensor-temperature",
      "name": "Temperature",
      "value": 17.87281,
      "state": "17.9 °C"
    },
    {
      "id": "sensor-humidity",
      "name": "Humidity",
      "value": 77.97218,
      "state": "78.0 %"
    }
  ]
}

Or at the very least, a simple list of available sensor IDs to enable discovery?

This is fundamental REST API design. When dealing with a collection (sensors), a GET request to the collection name should return a list of all items in that collection.

Now, some might argue: "Oh, but you can use the EventStream at /events to get sensor data."

No, I can’t. That endpoint is poorly designed as well.

• When a client connects, it does not immediately receive any sensor data—not even the last known values.
• Instead, the client must wait for the next sensor update, which happens at different intervals depending on each sensor’s configuration.
• This makes it useless for retrieving all values quickly, as a simple "connect, wait for a second, fetch all values, disconnect" approach fails if a sensor only updates every minute.
• Finally, a persistent connection isn’t feasible for many use cases (e.g., embedded devices or simple monitoring scripts).

Bottom line:

The REST API fails to follow standard best practices, forces clients into awkward and inefficient workarounds. It offers multiple ways to retrieve data, but each method comes with it's own pitfalls.

• If you query sensor states, you must query each sensor individually and magically know the names of the sensors... which is inefficient.
• If you use the EventStream, you don’t get the last known state immediately - which is impractical.

A well-designed REST API should make data discoverable, retrievable, and efficient. Right now the API is designed to do the opposite - it almost feels like some kind proprietary vendor lock-in design made to force people into HA.

[bradyjoh]

Couldn't agree more. Coming from Tasmota where a single API call can retrieve all connected sensors, I am looking for a way to grab all sensor data from an ESP32 flashed with ESPHome and I'm coming up short.

Tasmota, for reference:

curl "10.1.1.43/cm?cmnd=Status%200"

{"Status":{"removedforclarity, "StatusSNS":{"Time":"2025-11-17T21:37:50","BME280":{"Temperature":72.4,"Humidity":26.5,"DewPoint":36.0,"Pressure":760.5},"PressureUnit":"mmHg","TempUnit":"F"},evenmorestuff}