diff --git a/src/api/history/openApi.json b/src/api/history/openApi.json new file mode 100644 index 000000000..1b07ba121 --- /dev/null +++ b/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": {} + } + } +} diff --git a/src/api/history/openApi.ts b/src/api/history/openApi.ts new file mode 100644 index 000000000..f6820eed5 --- /dev/null +++ b/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() diff --git a/src/api/swagger.ts b/src/api/swagger.ts index 028b8719e..bf1a249fd 100644 --- a/src/api/swagger.ts +++ b/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((acc, apiRecord: OpenApiRecord) => { acc[apiRecord.name] = apiRecord return acc