Changes & Deprecations

The introduction of new REST APIs in version 2 and the move to an operations based model has resulted in some version 1 paths being flagged for deprecation.

It is recommended that applications and plugins referencing these deprecated paths update their operation to reference the version 2 paths.

Changes

The following changes have been implemented with the introduction of Resources API and apply to applications using the ./signalk/v2/resources endpoint.

Note: These changes DO NOT impact applications using the ./signalk/v1/resources endpoint.

1. Resource ID prefix assignment

The version 1 specification defined resource Ids with the following format urn:mrn:signalk:uuid:<UUIDv4>.

e.g. urn:mrn:signalk:uuid:18592f80-3425-43c2-937b-0be64b6be68c

The Resource API has dropped the use the prefix and ids are now just a uuidv4 value.

e.g. 18592f80-3425-43c2-937b-0be64b6be68c

This format is used for both accessing a resource e.g. /signalk/v1/api/resources/waypoints/18592f80-3425-43c2-937b-0be64b6be68c as well as the value within an href attribute.

Example:

{
   "name": "...",
   "descripton": "...",
   "href": "/resources/waypoints/18592f80-3425-43c2-937b-0be64b6be68c",
   ...
}

2. Resource Attributes

The Resources API has updated the definition of the following resources and may break applications that simply shift to using the v2 api without catering for the changes:

  • routes: removed the start, end properties.
  • waypoints: removed position attribute, added name, description and type attributes.
  • regions: removed geohash attribute, added name and description properties.
  • notes: removed geohash and region attributes, added href and properties attributes.
  • charts: There has been a significant changes to include support for WMS, WMTS and TileJSON sources.

Please see the Resources OpenAPI definition for details.

Deprecations:

1. courseGreatCircle, courseRhumbline paths

With the introduction of the Course API the following paths should now be considered deprecated:

  • /signalk/v1/api/vessels/self/navigation/courseGreatCircle
  • /signalk/v1/api/vessels/self/navigation/courseRhumbline

Note: The Course API does currently maintain values in these paths for the purposes of backward compatibility, but applications and plugins referencing these paths should plan to move to using the equivalent paths under /signalk/v2/api/vessels/self/navigation/course.