Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/stefanbossbaly/home-assistant-rest
Home Assistant Async REST API Rust Client
https://github.com/stefanbossbaly/home-assistant-rest
api home-assistant iot-platform rest rest-api
Last synced: 17 days ago
JSON representation
Home Assistant Async REST API Rust Client
- Host: GitHub
- URL: https://github.com/stefanbossbaly/home-assistant-rest
- Owner: StefanBossbaly
- License: mit
- Created: 2023-03-19T04:36:28.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2024-08-19T20:57:25.000Z (3 months ago)
- Last Synced: 2024-10-19T07:04:34.704Z (about 1 month ago)
- Topics: api, home-assistant, iot-platform, rest, rest-api
- Language: Rust
- Homepage: https://crates.io/crates/home-assistant-rest
- Size: 70.3 KB
- Stars: 8
- Watchers: 4
- Forks: 5
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Home Assistant REST  [](https://docs.rs/home-assistant-rest)
This project provides developers with a standard and ergonomic Rust API for
calling the various endpoints in Home Assistant's REST API. It handles the
serialization and deserialization of the requests and responses and allows the
developer to use the provided structures. Currently this project is still under
active development and the API might change at any time.
## Example Usage
```rust
use home_assistant_rest::{Client, StateEnum};
#[tokio::main]
async fn main() -> Result<(), Box> {
let base_url = "REPLACE_WITH_HASS_BASE_URL";
let token = "REPLACE_WITH_ACCESS_TOKEN";
let client = Client::new(base_url, token)?;
let api_status = client.get_api_status().await?;
if api_status.message != "API running." {
println!("API is NOT running");
} else {
println!("API is running, getting status of \"sun.sun\" entity");
let state_entity = client.get_states_of_entity("sun.sun").await?;
if let Some(state) = state_entity.state {
match state {
StateEnum::Boolean(x) => println!("Value is boolean with value {}", x),
StateEnum::Decimal(x) => println!("Value is decimal with value {}", x),
StateEnum::Integer(x) => println!("Value is integer with value {}", x),
StateEnum::String(x) => println!("Value is string with value \"{}\"", x),
}
} else {
println!("Value was not provided");
}
}
Ok(())
}
```
## Features
- `serde_debugging` (default: `false`) - Enables `with_debugging` functions that
function the same as their counterparts with the exception that they use the
[`serde_path_to_error`](https://crates.io/crates/serde_path_to_error) as the
deserialization adapter and will return `DeserializeFailed` variant that holds
the path to struct field that failed deserialization and the full response
from the endpoint. Serde errors can be very cryptic and very hard to debug.
These functions allow the developer to easily find field that failed
deserialization at the cost of saving the response as well as maintaining a
path to the current field during deserialization.
## API Status
| Endpoint | Request Type | Implemented | Tested |
| -------------------------------------- | ------------ | ----------- | ------ |
| `/api/` | GET | ✅ | ✅ |
| `/api/config` | GET | ✅ | ✅ |
| `/api/events` | GET | ✅ | ✅ |
| `/api/services` | GET | ✅ | ✅ |
| `/api/history/period/` | GET | ✅ | ✅ |
| `/api/logbook/` | GET | ✅ | ✅ |
| `/api/states` | GET | ✅ | ✅ |
| `/api/states/` | GET | ✅ | ✅ |
| `/api/error_log` | GET | ✅ | ✅ |
| `/api/camera_proxy/` | GET | ❌ | ❌ |
| `/api/calendars` | GET | ✅ | ✅ |
| `/api/calendars/` | GET | ✅ | ✅ |
| `/api/states/` | POST | ✅ | ✅ |
| `/api/events/` | POST | ✅ | ✅ |
| `/api/services//` | POST | ❌ | ❌ |
| `/api/template` | POST | ✅ | ✅ |
| `/api/config/core/check_config` | POST | ✅ | ✅ |
| `/api/intent/handle` | POST | ❌ | ❌ |
## Differences between the specification and implementation
Home Assistant provides a
[API specification](https://developers.home-assistant.io/docs/api/rest/) that
lists in the various different endpoints, their parameters and their output.
However when implementing this library I have come across a number of
discrepancies between the specification and the my local Home Assistant
instance. Here is a list of the differences I have found so far:
1. For the `/api/services` endpoint, the `services` attribute is listed in the
example as a list of strings. However testing locally the type for the
`services` attribute is actually a map.
2. For the `/api/camera_proxy/` endpoint, the only listed
parameters are the camera id and the time. However looking at the developer
tools panel, it shows that a unique token is also needed in order to retrieve
the image.
3. Serialization of non-string types, especially for the `state` attribute. I
have seen many entities that report their state as either an integer, decimal
or boolean but when that state is serialized in the JSON response, the type
is a string and not the underlying type. In order to work around this issue,
when deserializing the state we attempt to deserialize into the underlying
types first if that fails then we default to a string type. This is not ideal
as it is costly to parse various different types. In the future I will
consider adding an option that allows the user to opt-out of this "feature".
## Authors
Stefan Bossbaly
## License
This project is licensed under the MIT License - see the LICENSE file for
details
## Acknowledgments
- [Home Assistant](https://www.home-assistant.io/)
- [Home Assistant REST API](https://developers.home-assistant.io/docs/api/rest/)