signalk-server
Version:
An implementation of a [Signal K](http://signalk.org) server for boats.
359 lines • 17.2 kB
JavaScript
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.historyApiRecord = void 0;
const historyApiDoc = {
openapi: '3.0.0',
info: {
version: '0.0.1',
title: 'Signal K History API',
description: 'API for querying historical data, typically stored in a database. The actual storage backend is not defined by this API and can be implemented in various ways, typically as a plugin like [signalk-parquet](https://www.npmjs.com/package/signalk-parquet) and [signalk-to-influxdb2](https://www.npmjs.com/package/signalk-to-influxdb2). The most common use case for the API is to show graphs of past values.\n\n The time range can be defined as a combination of **from**, **to** and **duration** parameters. Omitted from and to parameters default to current moment in time, so that for example specifying just **duration** refers to the length of duration up to this moment.',
license: {
name: 'Apache 2.0',
url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
}
},
servers: [{ url: '/signalk/v2/api/history' }],
components: {
parameters: {
TimeRangeFrom: {
name: 'from',
in: 'query',
description: 'Start of the time range, inclusive as ISO 8601 timestamp',
schema: {
type: 'string',
format: 'date-time',
example: '2018-03-20T09:13:28Z'
}
},
TimeRangeDuration: {
name: 'duration',
in: 'query',
description: "Duration of the time range in seconds (integer) or as an ISO8601 Duration string. Can be specified with either 'from' or 'to'. If they are both omitted is relative to 'now'. See https://datatracker.ietf.org/doc/html/rfc3339#appendix-A",
schema: {
oneOf: [
{ type: 'integer', description: 'Duration in seconds' },
{
type: 'string',
format: 'duration',
description: 'ISO8601 Duration string',
example: 'PT15M'
}
]
}
},
TimeRangeTo: {
name: 'to',
in: 'query',
description: "End of the time range, inclusive. 'Now' if omitted",
schema: {
type: 'string',
format: 'date-time',
example: '2018-03-20T09:13:28Z'
}
},
ProviderIdParam: {
in: 'path',
name: 'id',
required: true,
description: 'Plugin id of the history provider.',
schema: { type: 'string', example: 'signalk-to-influxdb2' }
},
ProviderIdQuery: {
in: 'query',
name: 'provider',
description: 'Plugin id of the history provider the request will be directed to.',
schema: { type: 'string', example: 'signalk-to-influxdb2' }
}
},
responses: {
'200OKResponse': {
description: 'OK',
content: {
'application/json': {
schema: {
type: 'object',
required: ['state', 'statusCode', 'message'],
properties: {
state: { type: 'string', enum: ['COMPLETED'] },
statusCode: { type: 'number', enum: [200] },
message: { type: 'string' }
}
}
}
}
},
ErrorResponse: {
description: 'Failed operation',
content: {
'application/json': {
schema: {
type: 'object',
required: ['state', 'statusCode', 'message'],
properties: {
state: { type: 'string', enum: ['FAILED'] },
statusCode: { type: 'number' },
message: { type: 'string' }
}
}
}
}
}
}
},
// eslint-disable-next-line @typescript-eslint/no-explicit-any
paths: {}
};
// Dynamic example timestamps
const yesterday = new Date();
yesterday.setDate(yesterday.getDate() - 1);
historyApiDoc.paths = {
'/values': {
get: {
summary: 'Retrieve historical data',
description: 'Returns historical data series for the paths and time range specified in query parameters',
parameters: [
{
$ref: '#/components/parameters/TimeRangeFrom',
example: yesterday.toISOString()
},
{ $ref: '#/components/parameters/TimeRangeDuration' },
{
$ref: '#/components/parameters/TimeRangeTo',
example: new Date().toISOString()
},
{
name: 'paths',
in: 'query',
description: "Comma separated list of Signal K paths whose data should be retrieved, optional aggregation methods for each path as postfix separated by a colon, and optional source reference separated by a pipe (|). Aggregation methods: 'average' | 'min' | 'max' | 'first' | 'last' | 'mid' | 'middle_index' | 'sma' | 'ema'. The 'sma' (simple moving average) and 'ema' (exponential moving average) methods accept an optional numeric parameter separated by colon: for sma it is the number of samples, for ema it is the alpha value (0-1). If not provided, implementations should use sensible defaults. The source reference after | filters data to that specific source.",
example: 'navigation.speedOverGround:sma:5|n2k-on-ve.can0.115,navigation.speedThroughWater:max',
schema: { type: 'string' },
required: true
},
{
name: 'context',
in: 'query',
description: "Signal K context that the data is about, defaults to 'vessels.self'",
example: 'vessels.urn:mrn:imo:mmsi:123456789',
schema: { type: 'string' }
},
{
name: 'resolution',
in: 'query',
description: "Length of data sample time window in seconds or as a time expression ('1s', '1m', '1h', '1d'). If resolution is not specified the server should provide data in a reasonable time resolution, depending on the time range in the request.",
schema: { type: 'number', format: 'integer' }
},
{ $ref: '#/components/parameters/ProviderIdQuery' }
],
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, as UTC timestamp',
example: '2018-03-20T09:12:28Z'
},
to: {
type: 'string',
format: 'date-time',
description: 'End of the time range, inclusive, as UTC timestamp',
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'
},
sourceRef: {
type: 'string',
description: 'Source reference, present when the query specified a source filter for this path'
}
}
}
},
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. Missing data for a path is returned as null',
oneOf: [
{ type: 'string' },
{ type: 'number' },
{ type: 'null' },
{
type: 'array',
items: { type: 'number' }
}
]
}
},
example: [
['2023-11-09T02:45:38.160Z', 13.2, null, [-120.5, 59.2]]
]
}
}
}
}
}
}
}
}
},
'/contexts': {
get: {
summary: 'Get contexts that have some historical data',
description: 'Returns an array of contexts that have some historical data to query with /values for the specified time range',
parameters: [
{ $ref: '#/components/parameters/TimeRangeFrom' },
{ $ref: '#/components/parameters/TimeRangeDuration' },
{ $ref: '#/components/parameters/TimeRangeTo' },
{ $ref: '#/components/parameters/ProviderIdQuery' }
],
responses: {
'200': {
description: 'Array of contexts',
content: {
'application/json': {
schema: {
type: 'array',
items: {
type: 'string',
description: 'Signal K Context',
example: 'vessels.urn:mrn:imo:mmsi:123456789'
}
}
}
}
}
}
}
},
'/paths': {
get: {
summary: 'Get paths that have some historical data',
description: 'Returns an array of path that have some historical data to query with /values for the specified time range',
parameters: [
{ $ref: '#/components/parameters/TimeRangeFrom' },
{ $ref: '#/components/parameters/TimeRangeDuration' },
{ $ref: '#/components/parameters/TimeRangeTo' },
{ $ref: '#/components/parameters/ProviderIdQuery' }
],
responses: {
'200': {
description: 'Array of paths',
content: {
'application/json': {
schema: {
type: 'array',
items: {
type: 'string',
description: 'Signal K Path',
example: 'navigation.speedOverGround'
}
}
}
}
}
}
}
},
'/_providers': {
get: {
tags: ['Provider'],
summary: 'Retrieve list of registered history providers.',
responses: {
default: {
description: 'Return information about the registered history providers.',
content: {
'application/json': {
schema: {
type: 'object',
additionalProperties: {
type: 'object',
description: 'Provider status',
required: ['isDefault'],
properties: {
isDefault: {
type: 'boolean',
description: '`true` if this provider is set as the default.'
}
},
example: { isDefault: true }
}
}
}
}
}
}
}
},
'/_providers/_default': {
get: {
tags: ['Provider'],
summary: 'Get the default history provider id.',
responses: {
default: {
description: 'Returns the id of the provider that is the target of requests (if provider is not specified).',
content: {
'application/json': {
schema: {
type: 'object',
required: ['id'],
properties: {
id: {
type: 'string',
description: 'Provider identifier.'
}
},
example: { id: 'signalk-to-influxdb2' }
}
}
}
}
}
}
},
'/_providers/_default/{id}': {
parameters: [{ $ref: '#/components/parameters/ProviderIdParam' }],
post: {
tags: ['Provider'],
summary: 'Sets the default history provider.',
description: 'Sets the provider with the supplied `id` as the default.',
responses: {
default: { $ref: '#/components/responses/ErrorResponse' },
'200': { $ref: '#/components/responses/200OKResponse' }
}
}
}
};
exports.historyApiRecord = {
name: 'history',
path: '/signalk/v2/api/history',
apiDoc: historyApiDoc
};
//# sourceMappingURL=openApi.js.map