signalk-server

Version:

An implementation of a [Signal K](http://signalk.org) server for boats.

46 lines (43 loc) • 25.3 kB

HTML

<!DOCTYPE html><html class="default" lang="en" data-base="../../"><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>Resource Providers | Signal K</title><meta name="description" content="Documentation for Signal K"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="../../assets/style.css?cache=1750891486567"/><link rel="stylesheet" href="../../assets/highlight.css?cache=1750891486567"/><script defer src="../../assets/main.js?cache=1750891486567"></script><script async src="../../assets/icons.js?cache=1750891486567" id="tsd-icons-script"></script><script async src="../../assets/search.js?cache=1750891486567" id="tsd-search-script"></script><script async src="../../assets/navigation.js?cache=1750891486567" id="tsd-nav-script"></script><script async src="../../assets/hierarchy.js?cache=1750891486567" id="tsd-hierarchy-script"></script><link rel="stylesheet" href="../../assets/theme.css"/></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => window.app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><a href="../../index.html" class="title"><img src="../../assets/logo.svg" alt="Signal K"/></a><button id="tsd-search-trigger" class="tsd-widget" aria-label="Search"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../../assets/icons.svg#icon-search"></use></svg>Search</button><dialog id="tsd-search" aria-label="Search"><input role="combobox" id="tsd-search-input" aria-controls="tsd-search-results" aria-autocomplete="list" aria-expanded="true" autocapitalize="off" autocomplete="off" placeholder="Search the docs" maxLength="100"/><ul role="listbox" id="tsd-search-results"></ul><div id="tsd-search-status" aria-live="polite" aria-atomic="true"><div>Preparing search index...</div></div></dialog><div id="tsd-toolbar-links"><a href="https://discord.gg/uuZrwz4dCS" target="_blank" rel="noopener" class="toolbar-icon visible@s" aria-label="Discord"><svg width="24" height="24" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 512"><path d="M524.5 69.8a1.5 1.5 0 0 0 -.8-.7A485.1 485.1 0 0 0 404.1 32a1.8 1.8 0 0 0 -1.9 .9 337.5 337.5 0 0 0 -14.9 30.6 447.8 447.8 0 0 0 -134.4 0 309.5 309.5 0 0 0 -15.1-30.6 1.9 1.9 0 0 0 -1.9-.9A483.7 483.7 0 0 0 116.1 69.1a1.7 1.7 0 0 0 -.8 .7C39.1 183.7 18.2 294.7 28.4 404.4a2 2 0 0 0 .8 1.4A487.7 487.7 0 0 0 176 479.9a1.9 1.9 0 0 0 2.1-.7A348.2 348.2 0 0 0 208.1 430.4a1.9 1.9 0 0 0 -1-2.6 321.2 321.2 0 0 1 -45.9-21.9 1.9 1.9 0 0 1 -.2-3.1c3.1-2.3 6.2-4.7 9.1-7.1a1.8 1.8 0 0 1 1.9-.3c96.2 43.9 200.4 43.9 295.5 0a1.8 1.8 0 0 1 1.9 .2c2.9 2.4 6 4.9 9.1 7.2a1.9 1.9 0 0 1 -.2 3.1 301.4 301.4 0 0 1 -45.9 21.8 1.9 1.9 0 0 0 -1 2.6 391.1 391.1 0 0 0 30 48.8 1.9 1.9 0 0 0 2.1 .7A486 486 0 0 0 610.7 405.7a1.9 1.9 0 0 0 .8-1.4C623.7 277.6 590.9 167.5 524.5 69.8zM222.5 337.6c-29 0-52.8-26.6-52.8-59.2S193.1 219.1 222.5 219.1c29.7 0 53.3 26.8 52.8 59.2C275.3 311 251.9 337.6 222.5 337.6zm195.4 0c-29 0-52.8-26.6-52.8-59.2S388.4 219.1 417.9 219.1c29.7 0 53.3 26.8 52.8 59.2C470.7 311 447.5 337.6 417.9 337.6z"></path></svg></a><a href="https://github.com/SignalK/signalk-server" target="_blank" rel="noopener" class="toolbar-icon visible@s" aria-label="Discord"><svg width="24" height="24" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 496 512"><path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3 .3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6zm-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5 .3-6.2 2.3zm44.2-1.7c-2.9 .7-4.9 2.6-4.6 4.9 .3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9zM244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8zM97.2 352.9c-1.3 1-1 3.3 .7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1zm-10.8-8.1c-.7 1.3 .3 2.9 2.3 3.9 1.6 1 3.6 .7 4.3-.7 .7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3 .7zm32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3 .7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1zm-11.4-14.7c-1.6 1-1.6 3.6 0 5.9 1.6 2.3 4.3 3.3 5.6 2.3 1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2z"></path></svg></a><a href="#" class="tsd-widget menu" id="tsd-toolbar-menu-trigger" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="../../assets/icons.svg#icon-menu"></use></svg></a></div></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><ul class="tsd-breadcrumb" aria-label="Breadcrumb"><li><a href="../../Developing.html">Developing</a></li><li><a href="../Plugins.html">Plugins</a></li><li><a href="" aria-current="page">Resource Providers</a></li></ul></div><div class="tsd-panel tsd-typography"><h1 id="resource-provider-plugins" class="tsd-anchor-link">Resource Provider plugins<a href="#resource-provider-plugins" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../../assets/icons.svg#icon-anchor"></use></svg></a></h1>The Signal K server Resource API provides a common set operations for clients to interact with routes, waypoints, charts, etc but it does NOT provide the ability to persist or retrieve resources to / from storage. This functionality needs to be provided by one or more server plugins that interface with the Resource API to facilitate the storage and retrieval of resource data. These plugins are called Provider Plugins. Resource API architecture: <img src="../../media/resource_provider.svg" width="275"/> This de-coupling of request handling and data storage provides the flexibility to persist resource data in a variety of different storage types as well as Internet based services. <div class="tsd-alert tsd-alert-note"><div class="tsd-alert-title"><svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16" aria-hidden="true"><use href="../../assets/icons.svg#icon-alertNote"></use></svg>Note</div> Signal K server comes with the <a href="https://github.com/SignalK/signalk-server/tree/master/packages/resources-provider-plugin">resources-provider-plugin</a> pre-installed which persists resource data to the local file system. </div> <h2 id="resources-api" class="tsd-anchor-link">Resources API<a href="#resources-api" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../../assets/icons.svg#icon-anchor"></use></svg></a></h2>The <a href="../REST_APIs/Resources_API.html">Resources API</a> handles all client requests received via the <code>/signalk/v2/api/resources</code> path, before passing on the request to registered provider plugin(s). The Resources API performs the following operations when a request is received: <ol> <li>Checks for registered provider(s) for the resource type (i.e. route, waypoint, etc.)</li> <li>Checks that the required ResourceProvider methods are defined for the requested operation (i.e. POST, PUT, GET, DELETE)</li> <li>Performs an access control check</li> <li><code>POST</code> and <code>PUT</code> requests for Standard (Signal K defined) resource types are checked for validity of the submitted: <ul> <li><code>resource id</code></li> <li><code>resource data</code> against the OpenAPI definition.</li> </ul> </li> </ol> Only after successful completion of all these operations is the request passed on to the registered provider plugin(s). <hr> <h2 id="provider-plugins" class="tsd-anchor-link">Provider plugins<a href="#provider-plugins" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../../assets/icons.svg#icon-anchor"></use></svg></a></h2>A resource provider plugin is a Signal K server plugin that implements the <a href="../../_signalk/server-api/ResourceProvider.html" class="tsd-kind-interface">ResourceProvider</a> interface which: <ul> <li>Tells server the resource type(s) provided for by the plugin (i.e. route, waypoint, etc.)</li> <li>Registers the methods used to action requests passed from the server and perform the writing, retrieval and deletion of resources from storage. Note: The plugin MUST implement each method, even if that operation is NOT supported by the plugin!</li> </ul> <div class="tsd-alert tsd-alert-note"><div class="tsd-alert-title"><svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16" aria-hidden="true"><use href="../../assets/icons.svg#icon-alertNote"></use></svg>Note</div> Multiple providers can be registered for a resource type (e.g. 2 x chart providers) </div> Note: The Resource Provider is responsible for implementing the methods and returning data in the required format! <h2 id="registering-as-a-resource-provider" class="tsd-anchor-link">Registering as a Resource Provider<a href="#registering-as-a-resource-provider" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../../assets/icons.svg#icon-anchor"></use></svg></a></h2>To register a plugin as a provider for one or more resource types with the SignalK server, it must call the server's <a href="../../_signalk/server-api/ResourceProviderRegistry.html#registerresourceprovider" class="tsd-kind-method"><code>registerResourceProvider</code></a> function for each resource type being serviced during plugin startup. Example: Plugin registering as a routes & waypoints provider. <pre><code class="javascript">import { ResourceProvider } from '@signalk/server-api' module.exports = function (app) { const plugin = { id: 'mypluginid', name: 'My Resource Providerplugin' } const routesProvider: ResourceProvider = { type: 'routes', methods: { listResources: (params) => { fetchRoutes(params) ... }, getResource: (id, property?) => { getRoute(id, property) ... }, setResource: (id, value )=> { saveRoute(id, value) ... }, deleteResource: (id) => { deleteRoute(id, value) ... } } } const waypointsProvider: ResourceProvider = { type: 'waypoints', methods: { listResources: (params) => { fetchWaypoints(params) ... }, getResource: (id, property?) => { getWaypoint(id, property) ... }, setResource: (id, value )=> { saveWaypoint(id, value) ... }, deleteResource: (id) => { deleteWaypoint(id, value) ... } } } plugin.start = function(options) { ... try { app.registerResourceProvider(routesProvider) app.registerResourceProvider(waypointsProvider) } catch (error) { // handle error } } return plugin } </code><button type="button">Copy</button></pre> <h2 id="resource-provider-methods" class="tsd-anchor-link">Resource Provider Methods<a href="#resource-provider-methods" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="../../assets/icons.svg#icon-anchor"></use></svg></a></h2>A Resource Provider plugin must implement ALL methods in <a href="../../_signalk/server-api/ResourceProviderMethods.html" class="tsd-kind-interface"><code>ResourceProviderMethods</code></a> to service the requests passed from the server. Each method should return a Promise on success and <code>throw</code> on error, if a request is not serviced or is not implemented. Example: <pre><code class="javascript">// SignalK server plugin module.exports = function (app) { const plugin = { id: 'mypluginid', name: 'My Resource Providerplugin', start: options => { ... app.registerResourceProvider({ type: 'waypoints', methods: { listResources: (params) => { return new Promise( (resolve, reject) => { ... if (ok) { resolve(resource_list) } else { reject( new Error('Error fetching resources!')) } }) }, getResource: (id, property?) => { return new Promise( (resolve, reject) => { ... if (ok) { resolve(resource_list) } else { reject( new Error('Error fetching resource with supplied id!')) } }) }, setResource: (id, value )=> { throw( new Error('Not implemented!')) }, deleteResource: (id) => { throw( new Error('Not implemented!')) } } }) } } } </code><button type="button">Copy</button></pre> </div></div><div class="col-sidebar"><div class="page-menu"><details open class="tsd-accordion tsd-page-navigation"><summary class="tsd-accordion-summary"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="../../assets/icons.svg#icon-chevronDown"></use></svg><h3>On This Page</h3></summary><div class="tsd-accordion-details"><a href="#resources-api">Resources API</a><a href="#provider-plugins">Provider plugins</a><a href="#registering-as-a-resource-provider">Registering as a Resource Provider</a><a href="#resource-provider-methods">Resource Provider Methods</a></div></details></div><div class="site-menu"><nav class="tsd-navigation"><a href="../../modules.html">Signal K</a><ul class="tsd-small-nested-navigation" id="tsd-nav-container"><li>Loading...</li></ul></nav></div></div></div><footer>Generated using <a href="https://typedoc.org/" target="_blank">TypeDoc</a></footer><div class="overlay"></div></body></html>