diff --git a/gitbook-docs/resources.md b/gitbook-docs/resources.md new file mode 100644 index 000000000..4709f4200 --- /dev/null +++ b/gitbook-docs/resources.md @@ -0,0 +1,248 @@ +# Resources + +Resources are top level path in the Signal K API `/signalk/v1/api/resources` which comprises a collection of paths that provide access to additional information in order to aid and/or enhance navigation. + +Resource data can differ from _sensor_ data in the following ways: +- Is non-volatile _(not lost when server re-starts)_ +- Can represent a large collection of entries, each of which may be large in size +- Able to be created, updated and deleted by both applications and server processes + + +Resources are grouped under a specific path based on their type. The Signal K specification defines the following resource group paths and associated schemas: +- __routes__: `/signalk/v1/api/resources/routes` +- __waypoints__: `/signalk/v1/api/resources/waypoints` +- __notes__: `/signalk/v1/api/resources/notes` +- __regions__: `/signalk/v1/api/resources/regions` + + +Additional resource types can be defined under `/signalk/v1/api/resources/`, the assigned path should clearly identify the type of data hosted. + +_For example: Video steams from attached cameras could appear in `/signalk/v1/api/resources/video`._ + +Each resource entry within a group must be uniquely identified, this can be via a __name__ or __uuid__. + +``` +signalk/v1/api/resources/waypoints/urn:mrn:signalk:uuid:36f9b6b5-959f-46a1-8a68-82159742aadd_ + +signalk/v1/api/resources/video/bowCamera +``` + +Resource entries originating from another host or service will have a `$source` attribute containing a value identifying the source. + +Additionally resource entries may contain references to other resources in either the same or different group. + +_i.e. A route's `start` and `end` attributes contain a reference to a `waypoint` resource._ + +--- + +## Working with Resources + +The retrieval, creation, updating or deletion of resource entries is done by making the appropriate request to the Signal K server. + +_Note: Resource requests differ from other types of requests as there is no `context` required._ + +See [Request/Response](request_response.md) for more details on request/response behaviour in Signal K. + +--- + +## GETTING Resource Entries + +Resource entries are returned when either an HTTP or Delta __GET__ request is made to a resource path. + +- To return ALL of the entries within a resource group make a __GET__ request to the path for that group. _e.g. `/signalk/v1/api/resources/routes`_ + +- To return an individual resource entry make a __GET__ request to its path. _e.g. `/signalk/v1/api/resources/notes/urn:mrn:signalk:uuid:36f9b6b5-959f-46a1-8a68-82159742aadd`_ + +--- + +## CREATING a Resource Entry + +To create a resource a complete resource record is sent to the Signal K server via either an HTTP or Delta request. + +A resource is identified by a __uuid__ which will be generated by the Signal K server and assigned to the resource entry. + +The Signal K server will emit a Delta UPDATE message for the new resource upon success. + +### via HTTP + +Send an HTTP POST request to the appropriate resource path containing a payload of the following format: +```json +{ + "value": { }, + "source": "sourceId" +} +``` + +_Example:_ + +```json +POST http://localhost:3000/signalk/v1/api/vessels/resources/notes +{ + "value": { + "position":{ + "latitude": -35.02577800787516, + "longitude": 138.02825595260182 + }, + "title":"My Note", + "description":"My note description", + "url":"http://mynote/url", + "mimeType":"text/html" + }, + "source": "myApp", +} +``` + +The `source` field is optional. If a request is sent without the source and there is more than one source for the +value, the server should respond with a 400 (Bad Request) HTTP status code. + +### via Delta + +Send a PUT message to the appropriate resource path containing a payload of the following format: +```json +{ + "value": { }, + "path": "resources." +} +``` + +_Note: The `context` attribute is not required when making Resource requests._ + + +_Example:_ + +```json +{ + "requestId": "6b0e776f-811a-4b35-980e-b93405371bc5", + "put": [{ + "path": "resources.notes", + "value": { + "position":{ + "latitude": -35.02577800787516, + "longitude": 138.02825595260182 + }, + "title":"My Note", + "description":"My note description", + "url":"http://mynote/url", + "mimeType":"text/html" + } + }] +} +``` +--- + +## UPDATING a Resource Entry + +To update a resource entry a complete resource record is sent to the Signal K server via either an HTTP or Delta request. + +A resource to be updated is identified by the supplied __uuid__. + +The Signal K server will emit a Delta UPDATE message for the updated resource upon success. + +### via HTTP + +Send an HTTP PUT request to the path of the resource _(which includes the resource uuid)_ with a payload of the following format: +```json +{ + "value": { }, + "source": "sourceId" +} +``` + +_Example:_ +```json +PUT http://localhost:3000/signalk/v1/api/vessels/resources/notes/urn:mrn:signalk:uuid:36f9b6b5-959f-46a1-8a68-82159742aadd +{ + "value": { + "position":{ + "latitude": -35.02577800787516, + "longitude": 138.02825595260182 + }, + "title":"My Note", + "description":"My note description", + "url":"http://mynote/url", + "mimeType":"text/html" + }, + "source": "myApp", +} +``` + +### via Delta + +Send a PUT message to the appropriate resource path containing a payload of the following format: +```json +{ + "value": { }, + "path": "resources.." +} +``` + +_Note: The `context` attribute is not required when making Resource requests._ + + +```json +{ + "requestId": "6b0e776f-811a-4b35-980e-b93405371bc5", + "put": [{ + "path": "resources.notes.urn:mrn:signalk:uuid:36f9b6b5-959f-46a1-8a68-82159742aadd", + "value": { + "position":{ + "latitude": -35.02577800787516, + "longitude": 138.02825595260182 + }, + "title":"My Note", + "description":"My note description", + "url":"http://mynote/url", + "mimeType":"text/html" + } + }] +} +``` +--- + +## DELETING a Resource Entry + +To delete a resource entry the appropriate HTTP or Delta request is made to the relevant resource path. + +The Signal K server will emit a Delta UPDATE message for the deleted resource _(with a value of `null`)_ upon success. + +__Note:__ _Attempting to delete a resource may fail due to it containing links / references to other resources, permissions, etc._ See [Request/Response](request_response.md) for details. + +### via HTTP + +Send an HTTP DELETE request to the path of the resource that is to be removed. + +_Example:_ +``` +DELETE http://localhost:3000/signalk/v1/api/vessels/resources/notes/urn:mrn:signalk:uuid:36f9b6b5-959f-46a1-8a68-82159742aadd +``` + +### via a Delta + +Send a PUT message to the path of the resource to be removed with a value of `null`. + +```json +{ + "value": null, + "path": "resources.." +} +``` + +_Note: The `context` attribute is not required when making Resource requests._ + +_Example:_ + +```json +{ + "requestId": "6b0e776f-811a-4b35-980e-b93405371bc5", + "put": [{ + "path": "resources.notes.urn:mrn:signalk:uuid:36f9b6b5-959f-46a1-8a68-82159742aadd", + "value": null + }] +} +``` +--- + +## Handling invalid values + +The Signal K server should validate the value supplied within a request against the schema of the target resource group and return the relevent `state` and `statusCode` as detailed in [Request/Response](request_response.md) . +