jeans/developers.home-assistant
jeans/developers.home-assistant
1
0
Fork 0
mirror of https://github.com/home-assistant/developers.home-assistant.git synced 2025-04-19 10:57:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

Document API behaviour for service response data (#2137)

Browse Source 
* Document API behaviour for service response data

Adds documentation for a new query/JSON parameter called `return_response`. It allows users to retrieve service response data instead of state changes when calling a service using the API.

* Update documentation to match new implementation

* Fix typo

* Explicitly mention 400 in response

* Apply suggestions from code review

Co-authored-by: J. Nick Koston <nick+github@koston.org>

---------

Co-authored-by: Erik Montnemery <erik@montnemery.com>
Co-authored-by: J. Nick Koston <nick+github@koston.org>
This commit is contained in:
Jack Gaino 2025-03-17 11:01:28 -04:00 committed by GitHub
parent b638c1557d
commit d3f358deb3
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 61 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

65
docs/api/rest.md
View File

@ -636,7 +636,7 @@ You can pass an optional JSON object to be used as `service_data`.
}
```
Returns a list of states that have changed while the service was being executed.
Returns a list of states that have changed while the service was being executed, and optionally response data, if supported by the service.
```json
[
@ -655,6 +655,57 @@ Returns a list of states that have changed while the service was being executed.
]
```
:::tip
The result will include any states that changed while the service was being executed, even if their change was the result of something else happening in the system.
:::
If the service you're calling supports returning response data, you can retrieve it by adding `?return_response` to the URL. Your response will then contain both the list of changed entities and the service response data.
```json
{
"changed_states": [
{
"attributes": {},
"entity_id": "sun.sun",
"last_changed": "2024-04-22T20:45:54.418320-04:00",
"state": "below_horizon"
},
{
"attributes": {},
"entity_id": "binary_sensor.dropbox",
"last_changed": "2024-04-22T20:45:54.418320-04:00",
"state": "on"
}
],
"service_response": {
"weather.new_york_forecast": {
"forecast": [
{
"condition": "clear-night",
"datetime": "2024-04-22T20:45:55.173725-04:00",
"precipitation_probability": 0,
"temperature": null,
"templow": 6.0
},
{
"condition": "rainy",
"datetime": "2024-04-23T20:45:55.173756-04:00",
"precipitation_probability": 60,
"temperature": 16.0,
"templow": 4.0
}
]
}
}
}
```
:::note
Some services return no data, others optionally return response data, and some always return response data.
If you don't use `return_response` when calling a service that must return data, the API will return a 400. Similarly, you will receive a 400 if you use `return_response` when calling a service that doesn't return any data.
:::
Sample `curl` commands:
Turn the light on:
@ -692,9 +743,15 @@ curl \
http://localhost:8123/api/services/mqtt/publish
```
:::tip
The result will include any states that changed while the service was being executed, even if their change was the result of something else happening in the system.
:::
Retrieve daily weather forecast information:
```shell
curl \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TOKEN" \
-d '{"entity_id": "weather.forecast_home", "type": "daily"}' \
http://localhost:8123/api/services/weather/get_forecasts?return_response
```
</ApiEndpoint>