From 32d0a55f2965935eb9112f49a53d999b22110051 Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@koston.org>
Date: Sun, 21 Jun 2020 15:59:33 -0500
Subject: [PATCH] Update rest api for latest history and logbook changes (#587)

---
 docs/api/rest.md | 107 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 107 insertions(+)

diff --git a/docs/api/rest.md b/docs/api/rest.md
index a7bfb804..d02ba040 100644
--- a/docs/api/rest.md
+++ b/docs/api/rest.md
@@ -212,7 +212,10 @@ You can pass the following optional GET parameters:
 
 - `filter_entity_id=<entity_ids>` to filter on one or more entities - comma separated.
 - `end_time=<timestamp>` to choose the end of the period in URL encoded format (defaults to 1 day).
+- `minimal_response` to only return `last_changed` and `state` for states other than the first and last state (much faster).
+- `significant_changes_only` to only return signifcant state changes.
 
+Example without `minimal_response`
 ```json
 [
     [
@@ -240,6 +243,42 @@ You can pass the following optional GET parameters:
 ]
 ```
 
+Example with `minimal_response`
+```json
+[
+    [
+        {
+            "attributes": {
+                "friendly_name": "Weather Temperature",
+                "unit_of_measurement": "\u00b0C"
+            },
+            "entity_id": "sensor.weather_temperature",
+            "last_changed": "2016-02-06T22:15:00+00:00",
+            "last_updated": "2016-02-06T22:15:00+00:00",
+            "state": "-3.9"
+        },
+        {
+            "last_changed": "2016-02-06T22:20:00+00:00",
+            "state": "-2.9"
+        },
+        {
+            "last_changed": "2016-02-06T22:22:00+00:00",
+            "state": "-2.2"
+        },        
+        {
+            "attributes": {
+                "friendly_name": "Weather Temperature",
+                "unit_of_measurement": "\u00b0C"
+            },
+            "entity_id": "sensor.weather_temperature",
+            "last_changed": "2016-02-06T22:25:00+00:00",
+            "last_updated": "2016-02-06T22:25:00+00:00",
+            "state": "-1.9"
+        },
+    ]
+]
+```
+
 Sample `curl` commands:
 
 ```shell
@@ -248,6 +287,13 @@ curl -X GET -H "Authorization: Bearer ABCDEFGH" \
   http://localhost:8123/api/history/period/2016-12-29T00:00:00+02:00
 ```
 
+
+```shell
+curl -X GET -H "Authorization: Bearer ABCDEFGH" \
+  -H "Content-Type: application/json" \
+  http://localhost:8123/api/history/period/2016-12-29T00:00:00+02:00?minimal_response
+```
+
 ```shell
 curl -X GET -H "Authorization: Bearer ABCDEFGH" \
   -H "Content-Type: application/json" \
@@ -260,6 +306,67 @@ curl -X GET -H "Authorization: Bearer ABCDEFGH" \
   http://localhost:8123/api/history/period/2016-12-29T00:00:00+02:00?end_time=2016-12-31T00%3A00%3A00%2B02%3A00
 ```
 
+#### GET /api/logbook/&lt;timestamp>
+
+Returns an array of logbook entries.
+
+The `<timestamp>` (`YYYY-MM-DDThh:mm:ssTZD`) is optional and defaults to 1 day before the time of the request. It determines the beginning of the period.
+
+You can pass the following optional GET parameters:
+
+- `entity=<entity_id>` to filter on one entity.
+- `end_time=<timestamp>` to choose the end of period starting from the `<timestamp>` in URL encoded format.
+
+Example
+```json
+[
+  {
+		"context_user_id": null,
+		"domain": "alarm_control_panel",
+		"entity_id": "alarm_control_panel.area_001",
+		"message": "changed to disarmed",
+		"name": "Security",
+		"when": "2020-06-20T16:44:26.127295+00:00"
+	},
+	{
+		"context_user_id": null,
+		"domain": "homekit",
+		"entity_id": "alarm_control_panel.area_001",
+		"message": "send command alarm_arm_night for Security",
+		"name": "HomeKit",
+		"when": "2020-06-21T02:59:05.759645+00:00"
+	},
+	{
+		"context_user_id": null,
+		"domain": "alarm_control_panel",
+		"entity_id": "alarm_control_panel.area_001",
+		"message": "changed to armed_night",
+		"name": "Security",
+		"when": "2020-06-21T02:59:06.015463+00:00"
+	}
+]
+```
+
+Sample `curl` commands:
+
+```shell
+curl -X GET -H "Authorization: Bearer ABCDEFGH" \
+  -H "Content-Type: application/json" \
+  http://localhost:8123/api/logbook/2016-12-29T00:00:00+02:00
+```
+
+```shell
+curl -X GET -H "Authorization: Bearer ABCDEFGH" \
+  -H "Content-Type: application/json" \
+  'http://localhost:8123/api/logbook/2016-12-29T00:00:00+02:00?end_time=2099-12-31T00%3A00%3A00%2B02%3A00&entity=sensor.temperature'
+```
+
+```shell
+curl -X GET -H "Authorization: Bearer ABCDEFGH" \
+  -H "Content-Type: application/json" \
+  http://localhost:8123/api/logbook/2016-12-29T00:00:00+02:00?end_time=2099-12-31T00%3A00%3A00%2B02%3A00
+```
+
 #### GET /api/states
 
 Returns an array of state objects. Each state has the following attributes: entity_id, state, last_changed and attributes.