Document API behaviour for service response data #2137
Conversation
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.
|
According to home-assistant/architecture#1074, the REST API is no longer supported. Closing this. |
|
Reopened as home-assistant/core#115046 is making progress again. |
WalkthroughWalkthroughThe updates to the Changes
Recent review detailsConfiguration used: CodeRabbit UI Files selected for processing (1)
Additional comments not posted (5)
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (invoked as PR comments)
Additionally, you can add CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
docs/api/rest.md
Outdated
| 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. | ||
| ::: |
There was a problem hiding this comment.
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.
| 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. | |
| ::: |
| }, | ||
| { | ||
| "attributes": {}, | ||
| "entity_id": "process.Dropbox", |
There was a problem hiding this comment.
| "entity_id": "process.Dropbox", | |
| "entity_id": "binary_sensor.dropbox", |
There was a problem hiding this comment.
All entities in the state machine should always be lower case
There was a problem hiding this comment.
That's copy-pasted from another example in this same document.
developers.home-assistant/docs/api/rest.md
Line 390 in 5d9b6a8
developers.home-assistant/docs/api/rest.md
Line 651 in 5d9b6a8
Are those wrong too? They look like very old examples, if the date in the sample data is to be believed.
Proposed change
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.Type of change
Additional information
Summary by CodeRabbit
curlcommand example for retrieving daily weather forecast information.