[supersceded by #1381] Implement Course and Resources API

[panaaj]

This PR seeks to implement the Course API outlined in Signal K specification PR #629.

It is a branch of #1352 leveraging the getResource() method exposed by the Resources class.

[panaaj]

@tkurki @sbender9 I have a question regarding saving state on the server.
Specifically saving current course set by the API so that it survives a server restart.
Is there currently a mechanism to do this that could be used for this purpose?
I’m not sure persisting it with the server settings is a good approach.

[tkurki]

I think it is about time to bite the bullet and start using sqlite for this kind of stuff. If not there yet then separate settings json file per "subdomain" / api ?

Sqlite3 seems pretty abandoned and does not have prebuilt arm binaries, so takes long enough to compile that people believe install is stuck. There's also https://www.npmjs.com/package/better-sqlite3 but i don't have any experience with that.

[panaaj]

I have not used better-sqlite3 either.
For the course api use case alone an apis/course/settings.json is more than enough as it will only be written when changes to the course are made, but some kind of object store that is also exposed to plugins would be useful.

[panaaj]

I think it is about time to bite the bullet and start using sqlite for this kind of stuff. If not there yet then separate settings json file per "subdomain" / api ?

I have used a file .signalk/api/course/settings.json to store and retrieve state.
I think that this is PR is ready for review if the method to store state is acceptable.

I have a number of test curl commands I have used to test both the resources and course APIs.... Should these be located under the test folder in a folder called api?

[tkurki]

I think we should have runnable tests - curl commands should be easy enough to turn into sequences of fetch commands with some assertions sprinkled on top. You can just add the curl incantations someplace and I can do the fetches if you don't feel like doing that.

[tkurki]

A word on naming the persistence directory: I don't think this is about api but serverstate or something like along those lines.

[panaaj]

A word on naming the persistence directory: I don't think this is about api but serverstate or something like along those lines.

I have created the folder serverstate under the src folder which contains store.ts.
Hope this is more suitable.

[panaaj]

I think we should have runnable tests - curl commands should be easy enough to turn into sequences of fetch commands with some assertions sprinkled on top. You can just add the curl incantations someplace and I can do the fetches if you don't feel like doing that.

Following are the commands used for Course API testing:

Course Destination position
curl -H "Content-Type: application/json" -X PUT -d '{"position": {"latitude": -35.5, "longitude": 138.7}}' http://localhost:3000/signalk/v1/api/vessels/self/navigation/course/destination

Course Destination href
curl -H "Content-Type: application/json" -X PUT -d '{"href": "/resources/waypoints/urn:mrn:signalk:uuid:07894aba-f151-4099-aa4f-5e5773734b95"}' http://localhost:3000/signalk/v1/api/vessels/self/navigation/course/destination

Course RESTART
curl -H "Content-Type: application/json" -X PUT http://localhost:3000/signalk/v1/api/vessels/self/navigation/course/restart

Course ArrivalCircle
curl -H "Content-Type: application/json" -X PUT -d '{"value": 8000}' http://localhost:3000/signalk/v1/api/vessels/self/navigation/course/arrivalCircle

Course Activate Route pointIndex=0
curl -H "Content-Type: application/json" -X PUT -d '{"href": "/resources/routes/urn:mrn:signalk:uuid:0d95e282-3e1f-4521-8c30-8288addbdb69"}' http://localhost:3000/signalk/v1/api/vessels/self/navigation/course/activeRoute

Course Activate Route pointIndex=0 reverse=true
curl -H "Content-Type: application/json" -X PUT -d '{"href": "/resources/routes/urn:mrn:signalk:uuid:0d95e282-3e1f-4521-8c30-8288addbdb69", "reverse": true}' http://localhost:3000/signalk/v1/api/vessels/self/navigation/course/activeRoute

Course Next point
curl -H "Content-Type: application/json" -X PUT -d '{"value": 1 }' http://localhost:3000/signalk/v1/api/vessels/self/navigation/course/activeRoute/nextPoint

Course Previous point
curl -H "Content-Type: application/json" -X PUT -d '{"value": -1 }' http://localhost:3000/signalk/v1/api/vessels/self/navigation/course/activeRoute/nextPoint

Course set pointIndex=3
curl -H "Content-Type: application/json" -X PUT -d '{"value": 3 }' http://localhost:3000/signalk/v1/api/vessels/self/navigation/course/activeRoute/pointIndex

Clear Destination
curl -H "Content-Type: application/json" -X DELETE http://localhost:3000/signalk/v1/api/vessels/self/navigation/course/destination

Clear ActiveRoute
curl -H "Content-Type: application/json" -X DELETE http://localhost:3000/signalk/v1/api/vessels/self/navigation/course/activeRoute

[panaaj]

Following are the commands used for Resources API testing:

Using Signal K paths

New Route
curl -H "Content-Type: application/json" -X POST -d '{"name": "test route", "distance": 8000, "feature": {"type":"Feature", "geometry": {"type": "LineString", "coordinates": [[138.5, -38.6], [138.7, -38.2], [138.9, -38.0]] }, "properties":{} }}' http://localhost:3000/signalk/v1/api/resources/routes

Update Route
curl -H "Content-Type: application/json" -X PUT -d '{"name": "test route", "distance": 8000, "feature": {"type":"Feature", "geometry": {"type": "LineString", "coordinates": [[138.5, -38.6], [138.7, -38.2], [138.9, -38.0]] }, "properties":{} }}' http://localhost:3000/signalk/v1/api/resources/routes/urn:mrn:signalk:uuid:fb18904c-c0ce-46b5-a7bc-6fc5c4979723

DELETE Route
curl -H "Content-Type: application/json" -X DELETE http://localhost:3000/signalk/v1/api/resources/routes/urn:mrn:signalk:uuid:fb18904c-c0ce-46b5-a7bc-6fc5c4979723

**New Waypoint **
curl -H "Content-Type: application/json" -X POST -d '{"position": {"longitude": 138.5, "latitude": -38.6}, "feature": {"type":"Feature", "geometry": {"type": "Point", "coordinates": [138.5, -38.6] }, "properties":{} }}' http://localhost:3000/signalk/v1/api/resources/waypoints

Update Waypoint
curl -H "Content-Type: application/json" -X PUT -d '{"position": {"longitude": 138.5, "latitude": -38.6}, "feature": {"type":"Feature", "geometry": {"type": "Point", "coordinates": [138.5, -38.6] }, "properties":{} }}' \http://localhost:3000/signalk/v1/api/resources/waypoints/urn:mrn:signalk:uuid:ef7d8b1d-3c74-4257-b55f-8f52ce7452ba

DELETE Waypoint
curl -H "Content-Type: application/json" -X DELETE http://localhost:3000/signalk/v1/api/resources/waypoints/urn:mrn:signalk:uuid:ef7d8b1d-3c74-4257-b55f-8f52ce7452ba

Create Note
curl -H "Content-Type: application/json" -X POST -d '{"position": {"longitude": 138.5, "latitude": -38.6}, "title": "Test note", "description": "My test note"}' http://localhost:3000/signalk/v1/api/resources/notes

Update Note
curl -H "Content-Type: application/json" -X PUT -d '{"position": {"longitude": 138.5, "latitude": -38.6}, "title": "Test note", "description": "My test note"}' http://localhost:3000/signalk/v1/api/resources/notes/urn:mrn:signalk:uuid:ebbe61f8-586f-4383-8fa4-9c5fc0c2bf91

DELETE Note
curl -H "Content-Type: application/json" -X DELETE http://localhost:3000/signalk/v1/api/resources/notes/urn:mrn:signalk:uuid:ebbe61f8-586f-4383-8fa4-9c5fc0c2bf91

Create Region
curl -H "Content-Type: application/json" -X POST -d '{"feature": {"type":"Feature", "geometry": {"type": "Polygon", "coordinates": [[[138.5, -38.6], [138.7, -38.2], [138.9, -38.0],[138.5, -38.6]]] }, "properties":{} }}' http://localhost:3000/signalk/v1/api/resources/regions

Update Region
curl -H "Content-Type: application/json" -X PUT -d '{"feature": {"type":"Feature", "geometry": {"type": "Polygon", "coordinates": [[[138.5, -38.6], [138.7, -38.2], [138.9, -38.0],[138.5, -38.6]]] }, "properties":{} }}' http://localhost:3000/signalk/v1/api/resources/regions/urn:mrn:signalk:uuid:2c960383-f399-4a91-a5bc-3ea5065c39ad

Update Region (invalid polygon coordinates)
curl -H "Content-Type: application/json" -X PUT -d '{"feature": {"type":"Feature", "geometry": {"type": "Polygon", "coordinates": [[[138.5, -38.6], [138.7, -38.2], [138.9, -38.0]]] }, "properties":{} }}' http://localhost:3000/signalk/v1/api/resources/regions/urn:mrn:signalk:uuid:2c960383-f399-4a91-a5bc-3ea5065c39ad

DELETE Region
curl -H "Content-Type: application/json" -X DELETE http://localhost:3000/signalk/v1/api/resources/regions/urn:mrn:signalk:uuid:2c960383-f399-4a91-a5bc-3ea5065c39ad

Using API methods

New Waypoint
curl -H "Content-Type: application/json" -X POST -d '{"position": {"longitude": 138.5, "latitude": -38.6}, "name": "apiPosted Waypoint", "description":"My description"}' http://localhost:3000/signalk/v1/api/resources/set/waypoint

Update Waypoint
curl -H "Content-Type: application/json" -X PUT -d '{"position": {"longitude": 138.5, "latitude": -38.6}, "name": "apiPosted Waypoint", "description":"My description"}' http://localhost:3000/signalk/v1/api/resources/set/waypoint/urn:mrn:signalk:uuid:dc1d2f97-5368-4955-9441-90f921b6163b

INVALID Waypoint
curl -H "Content-Type: application/json" -X POST -d '{ "position": {"longitude": 188.5, "latitude": -38.6}, "name": "apiPosted invalid Waypoint", "description":"My invalid waypoint"}'
http://localhost:3000/signalk/v1/api/resources/set/waypoint

New Region
curl -H "Content-Type: application/json" -X POST -d '{ "geohash": "ww8p1r4t8", "name": "apiPosted region", "description":"My region"}' http://localhost:3000/signalk/v1/api/resources/set/region

New Route
curl -H "Content-Type: application/json" -X POST -d '{"name": "test api route", "points": [{"longitude": 138.5, "latitude": -38.6}, {"longitude": 139.5, "latitude": -37.6}, {"longitude": 140.5, "latitude": -36.6}] }' http://localhost:3000/signalk/v1/api/resources/set/route

INVALID Region
curl -H "Content-Type: application/json" -X POST -d '{ "points": [{"longitude": 138.5, "latitude": -38.6}, {"longitude": 139.5, "latitude": -37.6}, {"longitude": 140.5, "latitude": -36.6}], "name": "apiPosted region", "description":"My region"}' http://localhost:3000/signalk/v1/api/resources/set/region

[panaaj]

Actually I meant the data file location,

Have updated the saved state location to be .signalk/serverstate/course/settings.json

[tkurki]

Submitting what i have so far, see what you make of the comments.

[tkurki]

I was thinking about the tests: what if i contribute a sample test that

• sets a known starting state and connects ws
• makes the api call
• asserts that the state retrieved via http and the delta received over ws was what they should be

[panaaj]

supersceded by #1381