feature: Add Resources section

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": { <resource_data> },
+    "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": { <resource_data> },
+    "path": "resources.<resource_group>"
+}
+```
+
+_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": { <resource_data> },
+    "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": { <resource_data> },
+    "path": "resources.<resource_group>.<uuid>"
+}
+```
+
+_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.<resource_group>.<uuid>"
+}
+```
+
+_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) .
+