signalk-server

{ "openapi": "3.0.0", "info": { "version": "2.0.0", "title": "Signal K Resources API", "termsOfService": "http://signalk.org/terms/", "license": { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0.html" } }, "externalDocs": { "url": "http://signalk.org/specification/", "description": "Signal K specification." }, "servers": [ { "url": "/signalk/v2/api" } ], "tags": [ { "name": "providers", "description": "Resource Providers" }, { "name": "resources", "description": "Signal K resources" }, { "name": "routes", "description": "Route operations" }, { "name": "waypoints", "description": "Waypoint operations" }, { "name": "regions", "description": "Region operations" }, { "name": "notes", "description": "Note operations" }, { "name": "charts", "description": "Chart operations" } ], "components": { "schemas": { "Coordinate": { "type": "array", "maxItems": 3, "minItems": 2, "items": { "type": "number" } }, "LineStringCoordinates": { "type": "array", "items": { "$ref": "#/components/schemas/Coordinate" } }, "PolygonCoordinates": { "type": "array", "items": { "$ref": "#/components/schemas/LineStringCoordinates" } }, "MultiPolygonCoordinates": { "type": "array", "items": { "$ref": "#/components/schemas/PolygonCoordinates" } }, "Point": { "type": "object", "description": "GeoJSon Point geometry", "externalDocs": { "url": "http://geojson.org/geojson-spec.html#id2" }, "required": ["type"], "properties": { "type": { "type": "string", "enum": ["Point"] }, "coordinates": { "$ref": "#/components/schemas/Coordinate" } } }, "LineString": { "type": "object", "description": "GeoJSon LineString geometry", "externalDocs": { "url": "http://geojson.org/geojson-spec.html#id3" }, "required": ["type"], "properties": { "type": { "type": "string", "enum": ["LineString"] }, "coordinates": { "$ref": "#/components/schemas/LineStringCoordinates" } }, "example": { "type": "LineString", "coordinates": [ [24.897849923663273, 60.15202408867182], [24.902023936156723, 60.05997020643639], [24.67031474903851, 59.627962940557154], [24.777473968139503, 59.449626524251926], [24.758341055158922, 59.44208867188729] ] } }, "Polygon": { "type": "object", "description": "GeoJSon Polygon geometry", "externalDocs": { "url": "http://geojson.org/geojson-spec.html#id4" }, "required": ["type"], "properties": { "type": { "type": "string", "enum": ["Polygon"] }, "coordinates": { "$ref": "#/components/schemas/PolygonCoordinates" } } }, "MultiPolygon": { "type": "object", "description": "GeoJSon MultiPolygon geometry", "externalDocs": { "url": "http://geojson.org/geojson-spec.html#id6" }, "required": ["type"], "properties": { "type": { "type": "string", "enum": ["MultiPolygon"] }, "coordinates": { "$ref": "#/components/schemas/MultiPolygonCoordinates" } } }, "SignalKUuid": { "type": "string", "pattern": "[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-4[0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}$", "example": "ac3a3b2d-07e8-4f25-92bc-98e7c92f7f1a" }, "SignalKHref": { "type": "string", "pattern": "^/resources/(\\w*)/[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-4[0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}$" }, "SignalKPosition": { "type": "object", "required": ["latitude", "longitude"], "properties": { "latitude": { "type": "number", "format": "float" }, "longitude": { "type": "number", "format": "float" }, "altitude": { "type": "number", "format": "float" } } }, "HrefAttribute": { "type": "object", "required": ["href"], "properties": { "href": { "description": "Reference to a related resource. A pointer to the resource UUID.", "example": "/resources/waypoints/ac3a3b2d-07e8-4f25-92bc-98e7c92f7f1a", "allOf": [ { "$ref": "#/components/schemas/SignalKHref" } ] } } }, "PositionAttribute": { "type": "object", "required": ["position"], "properties": { "position": { "description": "Resource location.", "example": { "latitude": 65.4567, "longitude": 3.3452 }, "allOf": [ { "$ref": "#/components/schemas/SignalKPosition" } ] } } }, "Route": { "type": "object", "description": "Signal K Route resource", "required": ["feature"], "properties": { "name": { "type": "string", "description": "Route's common name", "example": "HSK to Old City Marina" }, "description": { "type": "string", "description": "A description of the route", "example": "Helsinki to Tallinn via Helsinki & Tallinn lighthouses" }, "distance": { "description": "Total distance from start to end", "type": "number" }, "feature": { "type": "object", "title": "Feature", "description": "A GeoJSON feature object which describes a route", "properties": { "geometry": { "$ref": "#/components/schemas/LineString" }, "properties": { "description": "Additional feature properties", "type": "object", "additionalProperties": true, "properties": { "coordinatesMeta": { "type": "array", "title": "Route point details", "description": "Metadata for each point within the route. Array length MUST be the same as length of coordinates array!", "items": { "oneOf": [ { "$ref": "#/components/schemas/RoutePointMeta" }, { "$ref": "#/components/schemas/HrefAttribute" } ] }, "example": [ { "name": "RtePt001" }, { "href": "/resources/waypoints/ac3a3b2d-07e8-4f25-92bc-98e7c92f7f1a" }, { "name": "RtePt003" }, { "name": "RtePt004" }, { "name": "RtePt005" } ] } } } } } } }, "RoutePointMeta": { "type": "object", "title": "Route point metadata", "description": "Attributes of a point within the route", "required": ["name"], "additionalProperties": true, "properties": { "name": { "description": "Point name / identifier", "type": "string", "example": "RtePt001" } } }, "Waypoint": { "description": "Signal K Waypoint resource", "type": "object", "required": ["feature"], "properties": { "name": { "type": "string", "description": "Waypoint's common name" }, "description": { "type": "string", "description": "A description of the waypoint" }, "type": { "type": "string", "description": "The type of point (e.g. Waypoint, PoI, Race Mark, etc)" }, "feature": { "type": "object", "title": "Feature", "description": "A Geo JSON feature object which describes a waypoint", "properties": { "geometry": { "$ref": "#/components/schemas/Point" }, "properties": { "description": "Additional feature properties", "type": "object", "additionalProperties": true } } } } }, "Region": { "description": "Signal K Region resource", "type": "object", "required": ["feature"], "properties": { "name": { "type": "string", "description": "Region's common name" }, "description": { "type": "string", "description": "A description of the region" }, "feature": { "type": "object", "title": "Feature", "description": "A Geo JSON feature object which describes the regions boundary", "properties": { "geometry": { "oneOf": [ { "$ref": "#/components/schemas/Polygon" }, { "$ref": "#/components/schemas/MultiPolygon" } ] }, "properties": { "description": "Additional feature properties", "type": "object", "additionalProperties": true } } } } }, "NoteBaseModel": { "description": "Signal K Note resource", "type": "object", "properties": { "title": { "type": "string", "description": "Title of note" }, "description": { "type": "string", "description": "Text describing note" }, "mimeType": { "type": "string", "description": "MIME type of the note" }, "url": { "type": "string", "description": "Location of the note" }, "properties": { "description": "Additional user defined note properties", "type": "object", "additionalProperties": true, "example": { "group": "My Note group", "author": "M Jones" } } } }, "Note": { "allOf": [ { "$ref": "#/components/schemas/NoteBaseModel" } ], "anyOf": [ { "$ref": "#/components/schemas/HrefAttribute" }, { "$ref": "#/components/schemas/PositionAttribute" } ] }, "TileLayerSource": { "description": "Attributes to describe a chart resource.", "type": "object", "required": ["type"], "properties": { "type": { "type": "string", "description": "Source type of map data.", "enum": ["tilelayer"], "default": "tilelayer", "example": "tilelayer" }, "bounds": { "description": "The maximum extent of available chart tiles in the format left, bottom, right, top.", "type": "array", "items": { "type": "number" }, "minItems": 4, "maxItems": 4, "example": [ 172.7499244562935, -41.27498133450632, 173.9166560895481, -40.70659187633642 ] }, "format": { "type": "string", "description": "The file format of the tile data.", "enum": ["jpg", "pbf", "png", "webp"], "example": "png" }, "maxzoom": { "type": "number", "description": "An integer specifying the maximum zoom level. MUST be >= minzoom.", "example": 27, "default": 0, "minimum": 0, "maximum": 30 }, "minzoom": { "type": "number", "description": "An integer specifying the minimum zoom level.", "example": 19, "default": 0, "minimum": 0, "maximum": 30 }, "scale": { "type": "number", "description": "Map scale", "minimum": 1, "default": 250000, "example": 250000 } } }, "MapServerSource": { "description": "Decribes Map server source types.", "type": "object", "required": ["type"], "properties": { "type": { "type": "string", "description": "Source type of map data.", "enum": ["tileJSON", "WMS", "WMTS", "mapstyleJSON", "S-57"], "example": "WMTS" } } }, "Chart": { "description": "Signal K Chart resource", "type": "object", "properties": { "identifier": { "type": "string", "description": "Chart identifier / number", "example": "NZ615" }, "name": { "type": "string", "description": "Chart name.", "example": "Tasman Bay", "default": null }, "description": { "type": "string", "description": "A text description of the chart.", "example": "Tasman Bay coastline", "default": null }, "url": { "type": "string", "description": "URL to tile / map source.", "example": "http://mapserver.org/wms/nz615" }, "layers": { "type": "array", "items": { "type": "string" }, "description": "List of chart layer ids.", "example": ["Restricted.Areas", "Fishing-Zones"] } }, "oneOf": [ { "$ref": "#/components/schemas/TileLayerSource" }, { "$ref": "#/components/schemas/MapServerSource" } ] }, "BaseResponseModel": { "description": "base model for resource entry response", "type": "object", "required": ["timestamp", "$source"], "properties": { "timestamp": { "type": "string" }, "$source": { "type": "string" } } }, "RouteResponseModel": { "allOf": [ { "$ref": "#/components/schemas/BaseResponseModel" }, { "$ref": "#/components/schemas/Route" } ] }, "WaypointResponseModel": { "allOf": [ { "$ref": "#/components/schemas/BaseResponseModel" }, { "$ref": "#/components/schemas/Waypoint" } ] }, "NoteResponseModel": { "allOf": [ { "$ref": "#/components/schemas/BaseResponseModel" }, { "$ref": "#/components/schemas/NoteBaseModel" } ], "oneOf": [ { "$ref": "#/components/schemas/HrefAttribute" }, { "$ref": "#/components/schemas/PositionAttribute" } ] }, "RegionResponseModel": { "allOf": [ { "$ref": "#/components/schemas/BaseResponseModel" }, { "$ref": "#/components/schemas/Region" } ] }, "ChartResponseModel": { "allOf": [ { "$ref": "#/components/schemas/BaseResponseModel" }, { "$ref": "#/components/schemas/Chart" } ] } }, "responses": { "200ActionResponse": { "description": "PUT, DELETE OK response", "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "enum": ["COMPLETED"] }, "statusCode": { "type": "number", "enum": [200] }, "id": { "$ref": "#/components/schemas/SignalKUuid" } }, "required": ["id", "statusCode", "state"] } } } }, "201ActionResponse": { "description": "POST OK response", "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "enum": ["COMPLETED"] }, "statusCode": { "type": "number", "enum": [201] }, "id": { "$ref": "#/components/schemas/SignalKUuid" } }, "required": ["id", "statusCode", "state"] } } } }, "ErrorResponse": { "description": "Failed operation", "content": { "application/json": { "schema": { "type": "object", "description": "Request error response", "properties": { "state": { "type": "string", "enum": ["FAILED"] }, "statusCode": { "type": "number", "enum": [404] }, "message": { "type": "string" } }, "required": ["state", "statusCode", "message"] } } } }, "RouteResponse": { "description": "Route record response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RouteResponseModel" } } } }, "WaypointResponse": { "description": "Waypoint record response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaypointResponseModel" } } } }, "NoteResponse": { "description": "Note record response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteResponseModel" } } } }, "RegionResponse": { "description": "Region record response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegionResponseModel" } } } }, "ChartResponse": { "description": "Chart record response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChartResponseModel" } } } } }, "parameters": { "ResourceTypeParam": { "name": "resourceType", "in": "path", "description": "Resource type", "required": true, "schema": { "type": "string" } }, "LimitParam": { "in": "query", "name": "limit", "description": "Maximum number of records to return", "schema": { "type": "integer", "format": "int32", "minimum": 1, "example": 100 } }, "DistanceParam": { "in": "query", "name": "distance", "description": "Limit results to resources that fall within a square area, centered around the vessel's position (or position parameter value if supplied), the edges of which are the sepecified distance in meters from the vessel.", "schema": { "type": "integer", "format": "int32", "minimum": 100, "example": 2000 } }, "BoundingBoxParam": { "in": "query", "name": "bbox", "description": "Limit results to resources that fall within the bounded area defined as lower left and upper right longitude, latatitude coordinates [lon1, lat1, lon2, lat2]", "style": "form", "explode": false, "schema": { "type": "array", "minItems": 4, "maxItems": 4, "items": { "type": "number", "format": "float", "minimum": -180, "maximum": 180 }, "example": [135.5, -25.2, 138.1, -28] } }, "PositionParam": { "in": "query", "name": "position", "description": "Location, in format [longitude, latitude], from where the distance parameter is applied.", "style": "form", "explode": false, "schema": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "number", "format": "float", "minimum": -180, "maximum": 180 }, "example": [135.5, -25.2] } }, "ZoomParam": { "in": "query", "name": "zoom", "description": "Zoom level of the map used by the client to display the returned resource entries. Refer: [OSM Zoom Levels](https://wiki.openstreetmap.org/wiki/Zoom_levels)", "schema": { "type": "integer", "format": "int32", "minimum": 1, "example": 4 } }, "ProviderParam": { "in": "query", "name": "provider", "description": "Plugin id of the resource provider to direct the request to (When multiple providers are registered for a resource type).", "style": "form", "explode": false, "schema": { "type": "string", "example": "my-provider" } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }, "cookieAuth": { "type": "apiKey", "in": "cookie", "name": "JAUTHENTICATION" } } }, "security": [{ "cookieAuth": [] }, { "bearerAuth": [] }], "paths": { "/resources": { "get": { "tags": ["resources"], "summary": "Retrieve list of available resource types", "responses": { "default": { "description": "List of available resource types identified by name", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "required": ["$source"], "properties": { "description": { "type": "string" }, "$source": { "type": "string" } } } } } } } } } }, "/resources/routes": { "parameters": [ { "$ref": "#/components/parameters/ProviderParam" } ], "get": { "tags": ["routes"], "summary": "Retrieve route resources", "parameters": [ { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/DistanceParam" }, { "$ref": "#/components/parameters/BoundingBoxParam" }, { "$ref": "#/components/parameters/PositionParam" }, { "$ref": "#/components/parameters/ZoomParam" } ], "responses": { "default": { "description": "An object containing Route resources, keyed by their UUID.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "allOf": [ { "$ref": "#/components/schemas/RouteResponseModel" } ] } } } } } } }, "post": { "tags": ["routes"], "summary": "New Route", "requestBody": { "description": "API request payload", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Route" } } } }, "responses": { "201": { "$ref": "#/components/responses/201ActionResponse" }, "default": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/resources/routes/{id}": { "parameters": [ { "name": "id", "in": "path", "description": "route id", "required": true, "schema": { "$ref": "#/components/schemas/SignalKUuid" } }, { "$ref": "#/components/parameters/ProviderParam" } ], "get": { "tags": ["routes"], "summary": "Retrieve route with supplied id", "responses": { "200": { "$ref": "#/components/responses/RouteResponse" }, "default": { "$ref": "#/components/responses/ErrorResponse" } } }, "put": { "tags": ["routes"], "summary": "Add / update a new Route with supplied id", "requestBody": { "description": "Route resource entry", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Route" } } } }, "responses": { "200": { "$ref": "#/components/responses/200ActionResponse" }, "default": { "$ref": "#/components/responses/ErrorResponse" } } }, "delete": { "tags": ["routes"], "summary": "Remove Route with supplied id", "responses": { "200": { "$ref": "#/components/responses/200ActionResponse" }, "default": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/resources/waypoints": { "parameters": [ { "$ref": "#/components/parameters/ProviderParam" } ], "get": { "tags": ["waypoints"], "summary": "Retrieve waypoint resources", "parameters": [ { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/DistanceParam" }, { "$ref": "#/components/parameters/BoundingBoxParam" }, { "$ref": "#/components/parameters/PositionParam" }, { "$ref": "#/components/parameters/ZoomParam" } ], "responses": { "default": { "description": "An object containing Waypoint resources, keyed by their UUID.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "allOf": [ { "$ref": "#/components/schemas/WaypointResponseModel" } ] } } } } } } }, "post": { "tags": ["waypoints"], "summary": "New Waypoint", "requestBody": { "description": "API request payload", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Waypoint" } } } }, "responses": { "201": { "$ref": "#/components/responses/201ActionResponse" }, "default": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/resources/waypoints/{id}": { "parameters": [ { "name": "id", "in": "path", "description": "waypoint id", "required": true, "schema": { "$ref": "#/components/schemas/SignalKUuid" } }, { "$ref": "#/components/parameters/ProviderParam" } ], "get": { "tags": ["waypoints"], "summary": "Retrieve waypoint with supplied id", "responses": { "200": { "$ref": "#/components/responses/WaypointResponse" }, "default": { "$ref": "#/components/responses/ErrorResponse" } } }, "put": { "tags": ["waypoints"], "summary": "Add / update a new Waypoint with supplied id", "requestBody": { "description": "Waypoint resource entry", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Waypoint" } } } }, "responses": { "200": { "$ref": "#/components/responses/200ActionResponse" }, "default": { "$ref": "#/components/responses/ErrorResponse" } } }, "delete": { "tags": ["waypoints"], "summary": "Remove Waypoint with supplied id", "responses": { "200": { "$ref": "#/components/responses/200ActionResponse" }, "default": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/resources/regions": { "parameters": [ { "$ref": "#/components/parameters/ProviderParam" } ], "get": { "tags": ["regions"], "summary": "Retrieve region resources", "parameters": [ { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/DistanceParam" }, { "$ref": "#/components/parameters/BoundingBoxParam" }, { "$ref": "#/components/parameters/PositionParam" }, { "$ref": "#/components/parameters/ZoomParam" } ], "responses": { "default": { "description": "An object containing Region resources, keyed by their UUID.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "allOf": [ { "$ref": "#/components/schemas/RegionResponseModel" } ] } } } } } } }, "post": { "tags": ["regions"], "summary": "New Region", "requestBody": { "description": "API request payload", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Region" } } } }, "responses": { "201": { "$ref": "#/components/responses/201ActionResponse" }, "default": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/resources/regions/{id}": { "parameters": [ { "name": "id", "in": "path", "description": "region id", "required": true, "schema": { "$ref": "#/components/schemas/SignalKUuid" } }, { "$ref": "#/components/parameters/ProviderParam" } ], "get": { "tags": ["regions"], "summary": "Retrieve region with supplied id", "responses": { "200": { "$ref": "#/components/responses/RegionResponse" }, "default": { "$ref": "#/components/responses/ErrorResponse" } } }, "put": { "tags": ["regions"], "summary": "Add / update a new Region with supplied id", "requestBody": { "description": "Region resource entry", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Region" } } } }, "responses": { "200": { "$ref": "#/components/responses/200ActionResponse" }, "default": { "$ref": "#/components/responses/ErrorResponse" } } }, "delete": { "tags": ["regions"], "summary": "Remove Region with supplied id", "responses": { "200": { "$ref": "#/components/responses/200ActionResponse" }, "default": { "$ref": "#/components/responses/ErrorResponse" } } } }, "/resources/notes": { "parameters": [ { "$ref": "#/components/parameters/ProviderParam" } ], "get": { "tags": ["notes"], "summary": "Retrieve note resources", "parameters": [ { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/DistanceParam" }, { "$ref": "#/components/parameters/BoundingBoxParam" }, { "$ref": "#/components/parameters/PositionParam" }, { "$ref": "#/components/parameters/ZoomParam" }, { "name": "href", "in": "query", "description": "Limit results to notes with matching resource reference", "example": "/resources/waypoints/ac3a3b2d-07e8-4f25-92bc-98e7c92f7f1a", "required": false, "explode": false, "schema": { "$ref": "#/components/schemas/SignalKHref" } } ], "responses": { "default": { "description": "An object containing Note resources, keyed by their UUID.", "content": { "application/json": { "schema": {