From c5f2209e4e0aca7ae50faa31a601edd53f6d042c Mon Sep 17 00:00:00 2001 From: Jack Gaino Date: Sat, 6 Apr 2024 14:43:27 -0400 Subject: [PATCH 1/4] 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. --- docs/api/rest.md | 32 ++++++++++++++++++++++++++++---- 1 file changed, 28 insertions(+), 4 deletions(-) diff --git a/docs/api/rest.md b/docs/api/rest.md index 96d437b4abb..a7688057b72 100644 --- a/docs/api/rest.md +++ b/docs/api/rest.md @@ -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 returns a list of states that have changed while the service was being executed. ```json [ @@ -655,6 +655,24 @@ 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 that instead of the list of state changes by either adding `?return_response` to the URL, or by adding `"return_response": true` to the JSON body. + +```json +{ + "return_response": true +} +``` + +:::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. +::: + Sample `curl` commands: Turn the light on: @@ -692,9 +710,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 +``` From 5e52cc2386da56acb8107c1eca7ce3f2fd09c013 Mon Sep 17 00:00:00 2001 From: Jack Gaino Date: Thu, 20 Jun 2024 23:04:18 -0400 Subject: [PATCH 2/4] Update documentation to match new implementation --- docs/api/rest.md | 37 +++++++++++++++++++++++++++++++++++-- 1 file changed, 35 insertions(+), 2 deletions(-) diff --git a/docs/api/rest.md b/docs/api/rest.md index a7688057b72..9c2bd5b4c4d 100644 --- a/docs/api/rest.md +++ b/docs/api/rest.md @@ -659,11 +659,44 @@ By default, a call will returns a list of states that have changed while the ser 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 that instead of the list of state changes by either adding `?return_response` to the URL, or by adding `"return_response": true` to the JSON body. +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 { - "return_response": true + "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", + "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 + } + ] + } + } } ``` From 74c03c63821442709e24be46b6f754b01a2aa2ed Mon Sep 17 00:00:00 2001 From: Jack Gaino Date: Thu, 20 Jun 2024 23:05:01 -0400 Subject: [PATCH 3/4] Fix typo --- docs/api/rest.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/rest.md b/docs/api/rest.md index 9c2bd5b4c4d..4a53a6a8f1b 100644 --- a/docs/api/rest.md +++ b/docs/api/rest.md @@ -636,7 +636,7 @@ You can pass an optional JSON object to be used as `service_data`. } ``` -By default, a call will 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 [ From 5d9b6a8a7658ed4dee96fd523f337ee16b7e4d17 Mon Sep 17 00:00:00 2001 From: Jack Gaino Date: Wed, 31 Jul 2024 23:07:31 -0400 Subject: [PATCH 4/4] Explicitly mention 400 in response --- docs/api/rest.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/rest.md b/docs/api/rest.md index 4a53a6a8f1b..82584b56f33 100644 --- a/docs/api/rest.md +++ b/docs/api/rest.md @@ -703,7 +703,7 @@ If the service you're calling supports returning response data, you can retrieve :::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. +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: