feature: Add Resources section

[panaaj]

As per issue #540 the specification could benefit from the addition of a Resources section to describe the way in which to work with these data items.

The initial content outlines the proposed creation, updating and deletion of resources and also proposes some basic filters to use when retrieving resources to limit the number of records returned.

As there is no documented way of supplying parameters to a Delta message I have taken a leap and proposed a params attribute for a get delta message.

I have referenced and aligned with other parts of the specification where possible.
Also tried to align POST and PUT requests with common use patterns.

There probably needs to be some text around security and accessing individual resource records as well.

Some other operational behaviour may also need to be specified e.g. Should the creation, updating and deletion of a resource trigger a delta update message?
I would assume yes but it's probably best that expected behaviour is specified.

[panaaj]

Resources can link / reference to other resources e.g. Route start and end link to waypoint records.
If a route is deleted should the associated a start and end waypoints be deleted as well?

[rob42]

Resources can link / reference to other resources e.g. Route start and end link to waypoint records.
If a route is deleted should the associated a start and end waypoints be deleted as well?

I think this is implementation specific. Obviously you should not delete a resource that is referenced from elsewhere, but I dont think thats a part of the signalk specification. The spec should say that " deletion is attempted and may fail, eg if the resource is referenced from elsewhere, or permissions etc. See request/response"

[rob42]

I think the params object is good, but we need to make it a generic part of signalk to use it well.

Also naming needs to be collision-free and suitable for any circumstance, So:

"params": { 
       //one (or more?) of
        "geo": {radius": 10000, //meters
                   "bounds": [138.23, -38.123, 139.76,-37.89], //array[ W-lon, S-lat, E-lon, N-lat ], eg SW to NE rectangle
                   "hash": "ssdfrt" 
                   },
          "limit": 20,
          "fromRecord": 0
}

Need generic params for recordCount in response too. Im thinking along the lines of SQL, and REST results paging...

[panaaj]

Should then the http parameters format align to make them similar to stream api?
e.g. ?filter={geo: {radius:1000} }

[rob42]

Is that valid http? Probably geo.radius=1000&geo.etc would be more std

[panaaj]

Parameters will likely need to encompass:

• Generic values e.g. limit=xxx, etc
• Collections like e.g. geo.radius=xxx, etc
  and
• Resource attributes e.g. note/region, region/geohash, chart/scale, etc

As resources have few common attributes, it would make it easier to identify an attribute used as a parameter if it were:

1. name-spaced i.e. note.region
   OR
2. Scoped with attr e.g. attr.region=xxx

So a query for all notes attached to the same region would be something like ../resources/notes?attr.region=123456

And clearly identified in use with others ../resources/notes?attr.region=123456&limit=200&geo.radius=1000

[fabdrol]

@panaaj @rob42 what's the status of this, more work required? If so @rob42 can you review and clearly identify what @panaaj should do to finish this PR?

[panaaj]

Given the intent of this PR was to have resources represented in the spec I have removed the section that talked about the ability to filter returned records as this needs more consideration.

There are clearly implementation considerations as well as specification additions to be made to add entry filtering, delta parameters, etc so rather than hold up this PR I have removed them.

@fabdrol @rob42