feature: add History API

src/api/history/openApi.json

@@ -0,0 +1,173 @@
+{
+  "openapi": "3.0.0",
+  "info": {
+    "version": "0.0.1",
+    "title": "Signal K History API",
+    "license": {
+      "name": "Apache 2.0",
+      "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
+    }
+  },
+  "servers": [
+    {
+      "url": "/signalk/v2/api/history"
+    }
+  ],
+  "components": {},
+  "security": [
+    {
+      "cookieAuth": []
+    },
+    {
+      "bearerAuth": []
+    }
+  ],
+  "paths": {
+    "/values": {
+      "get": {
+        "summary": "Retrive historical data",
+        "description": "Returns historical data series for the paths and time range specified in query parameters",
+        "parameters": [
+          {
+            "in": "query",
+            "name": "from",
+            "description": "Start of the time range, inclusive",
+            "schema": {
+              "type": "string",
+              "format": "date-time"
+            },
+            "required": true
+          },
+          {
+            "in": "query",
+            "name": "to",
+            "description": "End of the time range, inclusive",
+            "schema": {
+              "type": "string",
+              "format": "date-time"
+            },
+            "required": true
+          },
+          {
+            "in": "query",
+            "name": "context",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "in": "query",
+            "name": "interval",
+            "description": "Length of data sample time windows",
+            "schema": {
+              "type": "number",
+              "format": "integer"
+            }
+          },
+          {
+            "in": "query",
+            "name": "paths",
+            "description": "Comma separated ist of Signal K paths whose data should be retrieved, optional aggregation methods for each path as postfix separated by a colon. Aggregation methods: average(default), min, max, first",
+            "example": "navigation.speedOverGround,navigation.speedThroughWater:max",
+            "schema": {
+              "type": "string"
+            },
+            "required": true
+          },
+          {
+            "in": "query",
+            "name": "format",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Series data with header",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": ["context", "", "target"],
+                  "properties": {
+                    "context": {
+                      "type": "string",
+                      "description": "Signal K context that the data is about",
+                      "example": "vessels.urn:mrn:imo:mmsi:123456789"
+                    },
+                    "range": {
+                      "type": "object",
+                      "properties": {
+                        "from": {
+                          "type": "string",
+                          "format": "date-time",
+                          "description": "Start of the time range, inclusive",
+                          "example": "2018-03-20T09:12:28Z"
+                        },
+                        "to": {
+                          "type": "string",
+                          "format": "date-time",
+                          "description": "End of the time range, inclusive",
+                          "example": "2018-03-20T09:13:28Z"
+                        }
+                      }
+                    },
+                    "values": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "path": {
+                            "type": "string",
+                            "description": "Signal K path"
+                          },
+                          "method": {
+                            "type": "string",
+                            "description": "Aggregation method"
+                          }
+                        }
+                      }
+                    },
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "array",
+                        "items": {
+                          "description": "Data for a point in time. The first array element is the timestamp in ISO 8601 format",
+                          "oneOf": [
+                            {
+                              "type": "string"
+                            },
+                            {
+                              "type": "number"
+                            },
+                            {
+                              "type": "array",
+                              "items": {
+                                "type": "number"
+                              }
+                            }
+                          ]
+                        }
+                      },
+                      "example": [
+                        ["2023-11-09T02:45:38.160Z", 13.2, null, [-120.5, 59.2]]
+                      ]
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/contexts": {
+      "get": {}
+    },
+    "/paths": {
+      "get": {}
+    }
+  }
+}

src/api/history/openApi.ts

@@ -0,0 +1,15 @@
+import { OpenApiDescription } from '../swagger'
+import courseApiDoc from './openApi.json'
+
+export const historyApiRecord = {
+  name: 'history',
+  path: '/signalk/v2/api/history',
+  apiDoc: courseApiDoc as unknown as OpenApiDescription
+}
+
+const yesterday = new Date()
+yesterday.setDate(yesterday.getDate() - 1)
+courseApiDoc.paths['/values'].get.parameters[0].example =
+  yesterday.toISOString()
+courseApiDoc.paths['/values'].get.parameters[1].example =
+  new Date().toISOString()

src/api/swagger.ts

@@ -8,6 +8,7 @@ import { resourcesApiRecord } from './resources/openApi'
 import { securityApiRecord } from './security/openApi'
 import { discoveryApiRecord } from './discovery/openApi'
 import { appsApiRecord } from './apps/openApi'
+import { historyApiRecord } from './history/openApi'
 import { PluginId, PluginManager } from '../interfaces/plugins'
 import { Brand } from '@signalk/server-api'
 
@@ -29,7 +30,8 @@ const apiDocs = [
   securityApiRecord,
   courseApiRecord,
   notificationsApiRecord,
-  resourcesApiRecord
+  resourcesApiRecord,
+  historyApiRecord
 ].reduce<ApiRecords>((acc, apiRecord: OpenApiRecord) => {
   acc[apiRecord.name] = apiRecord
   return acc