Document API behaviour for service response data

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 return a list of states that have changed while the service was being executed.
 
 ```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": "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
+                }
+            ]
+        }
+    }
+}
+```
+
+:::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>