Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document API behaviour for service response data #2137

Open
wants to merge 5 commits into
base: master
Choose a base branch
from
+61 −4
Open

Document API behaviour for service response data #2137

Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
c5f2209
Document API behaviour for service response data
iamjackg Apr 6, 2024
5e52cc2
Update documentation to match new implementation
iamjackg Jun 21, 2024
74c03c6
Fix typo
iamjackg Jun 21, 2024
058c2c7
Merge branch 'master' into patch-1
iamjackg Aug 1, 2024
5d9b6a8
Explicitly mention 400 in response
iamjackg Aug 1, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 61 additions & 4 deletions docs/api/rest.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
By default, a call will return a list of states that have changed while the service was being executed.

```json
[
Expand All @@ -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.
iamjackg marked this conversation as resolved.
Show resolved Hide resolved

```json
{
"changed_states": [
{
"attributes": {},
"entity_id": "sun.sun",
"last_changed": "2024-04-22T20:45:54.418320-04:00",
"state": "below_horizon"
},
{
"attributes": {},
"entity_id": "process.Dropbox",
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"entity_id": "process.Dropbox",
"entity_id": "binary_sensor.dropbox",

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All entities in the state machine should always be lower case

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's copy-pasted from another example in this same document.

developers.home-assistant/docs/api/rest.md

Line 390 in 5d9b6a8

"entity_id": "process.Dropbox",

developers.home-assistant/docs/api/rest.md

Line 651 in 5d9b6a8

"entity_id": "process.Dropbox",

Are those wrong too? They look like very old examples, if the date in the sample data is to be believed.

"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 an error. Similarly, you will receive an error if you use `return_response` when calling a service that doesn't return any data.
:::
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Improve error handling documentation for return_response.

The note about receiving an error if return_response is misused is crucial. Clarify what types of errors users can expect (e.g., HTTP status codes) to improve their ability to handle these cases programmatically.

+ For example, using `return_response` incorrectly might result in a `400 Bad Request` error, indicating that the parameter was not expected for the called service.
Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
If you don't use `return_response` when calling a service that must return data, the API will return an error. Similarly, you will receive an error if you use `return_response` when calling a service that doesn't return any data.
:::
If you don't use `return_response` when calling a service that must return data, the API will return an error. Similarly, you will receive an error if you use `return_response` when calling a service that doesn't return any data.
For example, using `return_response` incorrectly might result in a `400 Bad Request` error, indicating that the parameter was not expected for the called service.
:::


Sample `curl` commands:

Turn the light on:
Expand Down Expand Up @@ -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>

Expand Down