From 4ed85ac7edeadf1cf7f5b7aa741255e95ebca594 Mon Sep 17 00:00:00 2001 From: Adrian Panazzolo <38519157+panaaj@users.noreply.github.com> Date: Thu, 14 Mar 2019 16:48:48 +1030 Subject: [PATCH 01/10] Add Resources section --- gitbook-docs/resources.md | 346 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 346 insertions(+) create mode 100644 gitbook-docs/resources.md diff --git a/gitbook-docs/resources.md b/gitbook-docs/resources.md new file mode 100644 index 000000000..8f7eac2b8 --- /dev/null +++ b/gitbook-docs/resources.md @@ -0,0 +1,346 @@ +# Resources + +Resources are collections of objects that are used to represent data that serves as additional information to aid with navigation, etc. + +Resources are: +- Usually persisted in a non-volatile data store _(i.e. not lost when server re-starts)_ +- Potentially large in number and / or record size +- Able to be created, updated and deleted by both applications and server processes +- A top level path in the Signal K API: `/signalk/v1/api/resources/*` + +Resource entries: +- Of a specific type are grouped under a specific path _i.e. `/signalk/v1/api/resources/waypoints`_ + +- Are identified by a __uuid__. _e.g. `urn:mrn:signalk:uuid:36f9b6b5-959f-46a1-8a68-82159742aadd`_ + +- Originating from other vessels will have a `$source` attribute that contains the id of the source vessel. + +- May contain references to other resources in either the same or different group. _i.e. A route's `start` and `end` attribute contains 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`_ + + +### Restricting the number of returned entries + +As the number of entries within a specific resource group can be large, you can provide parameters with your request to limit the number of entries returned. + +These parameters can be used individually or together to return the required resource entries. + +`GET "/signalk/v1/api/resources/routes?bounds=r1f2r&maxcount=200"` + +#### 1. Restrict by Bounded Area + +You can request resources that fall within a bounded geographic area by using the `bounds` parameter with a __geohash__ to define the size of the bounded area. + +### Via HTTP + +`GET "/signalk/v1/api/resources/routes?bounds=r1f2r"` + +### Via a Delta + +```json +{ + "requestId": "6b0e776f-811a-4b35-980e-b93405371bc5", + "get": [{ + "path": "resources.notes", + "params": { "bounds": "r1f2r" } + }] +} +``` + +#### 2. Specify maximum number of returned entries + +You can specify the maximum number of resource entries that are returned by using the `maxcount` parameter. + +### Via HTTP + +`GET "/signalk/v1/api/resources/routes?maxcount=200"` + +### Via a Delta + +```json +{ + "requestId": "6b0e776f-811a-4b35-980e-b93405371bc5", + "get": [{ + "path": "resources.notes", + "params": { "maxcount": 200 } + }] +} +``` + +#### Implementation specific parameters + +Specific use cases may require a richer set of options to target the entries to be returned. In these cases implementors can provide their own parameters for use in conjunction with those defined above as part of their product / solution. + +### Via HTTP + +`GET "/signalk/v1/api/resources/routes?myparam=myparam_value&maxcount=150"` + +### Via a Delta + +```json +{ + "requestId": "6b0e776f-811a-4b35-980e-b93405371bc5", + "get": [{ + "path": "resources.notes", + "params": { + "bounds": "r1f2r", + "maxcount": 200 + } + }] +} +``` + +--- + +## CREATING a Resource Entry + +### Via HTTP + +__1. Where the server will generate the UUID of the new resource:__ + +Send an HTTP POST request to the appropriate resource path containing a payload of the following format: +```json +{ + "value": { ... }, + "source": "sourceId" +} +``` + +__2. Where the client will generate the UUID of the new resource:__ + +Send an HTTP PUT request to the appropriate resource path containing a payload of the following format: +```json +{ + "value": { + "my_uuid": { ... } + }, + "source": "sourceId" +} +``` + +_Example: Server creates resource uuid_ +```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", +} +``` + +_Example: Client creates resource uuid_ + +```json +PUT http://localhost:3000/signalk/v1/api/vessels/resources/notes +{ + "value": { + "urn:mrn:signalk:uuid:36f9b6b5-959f-46a1-8a68-82159742aadd": { + "position": { + "latitude": -35.025778007875, + "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 a Delta + +__1. Where the server will generate the UUID of the new resource:__ + +Send a PUT message to the appropriate resource path containing a payload of the following format: +```json +{ + "value": { ... }, + "path": "resources." +} +``` + +__2. Where the client will generate the UUID of the new resource:__ + +Send a PUT message to the appropriate resource path containing a payload of the following format: +```json +{ + "value": { + "my_uuid": { ... } + }, + "path": "resources." +} +``` + +_Note: The `context` attribute is not required when making Resource requests._ + + +_Example: Server creates resource uuid_ + +```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" + } + }] +} +``` + +_Example: Client creates resource uuid_ + +```json +{ + "requestId": "6b0e776f-811a-4b35-980e-b93405371bc5", + "put": [{ + "path": "resources.notes", + "value": { + "urn:mrn:signalk:uuid:36f9b6b5-959f-46a1-8a68-82159742aadd": { + "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 + +### Via HTTP + +Send an HTTP PUT request to the path of the resource 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 a 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 + + +### Via HTTP + +Send an HTTP DELETE request to the path of the resource. + +`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 appropriate resource path containing a payload with a value of `null`. + +_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": 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) . + From 11ddda87f62f6b085ae0dce6815e65c3e0829893 Mon Sep 17 00:00:00 2001 From: Adrian Panazzolo <38519157+panaaj@users.noreply.github.com> Date: Sat, 16 Mar 2019 14:50:25 +1030 Subject: [PATCH 02/10] trigger Delta UPDATE when resource record is added, deleted or changes --- gitbook-docs/resources.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/gitbook-docs/resources.md b/gitbook-docs/resources.md index 8f7eac2b8..9d0720882 100644 --- a/gitbook-docs/resources.md +++ b/gitbook-docs/resources.md @@ -112,6 +112,8 @@ Specific use cases may require a richer set of options to target the entries to ## CREATING a Resource Entry +_Note: The creation, update or deletion of a resource should trigger the relevent Delta UPDATE message._ + ### Via HTTP __1. Where the server will generate the UUID of the new resource:__ From b90709f65a85b17e85e6b06078fa4921a4781edd Mon Sep 17 00:00:00 2001 From: Adrian Panazzolo <38519157+panaaj@users.noreply.github.com> Date: Sun, 17 Mar 2019 15:48:10 +1030 Subject: [PATCH 03/10] Added additonal filters --- gitbook-docs/resources.md | 76 +++++++++++++++++++++++++++++++++------ 1 file changed, 65 insertions(+), 11 deletions(-) diff --git a/gitbook-docs/resources.md b/gitbook-docs/resources.md index 9d0720882..4aaa65056 100644 --- a/gitbook-docs/resources.md +++ b/gitbook-docs/resources.md @@ -43,24 +43,61 @@ As the number of entries within a specific resource group can be large, you can These parameters can be used individually or together to return the required resource entries. -`GET "/signalk/v1/api/resources/routes?bounds=r1f2r&maxcount=200"` +``` +GET "/signalk/v1/api/resources/routes?geohash=r1f2r&maxcount=200" +``` #### 1. Restrict by Bounded Area -You can request resources that fall within a bounded geographic area by using the `bounds` parameter with a __geohash__ to define the size of the bounded area. +You can request resources that fall within a bounded geographic area by using one of the following parameters: + +- __GeoHash__: +Use the `geohash` parameter along with a __geohash__ to define the bounded area from within which resources will be returned. + +- __SW / NE coordinates__: +Use the `bounds` parameter to suppy an array `[x1,y1,x2,y2]` that defines the SW and NE corners of the bounded area from within which resources will be returned. + +- __Distance from vessel__: +Use the `distance` parameter to specify the number of meters from the vessel that the bounded area (square) from within which resources will be returned. + +_Examples:_ ### Via HTTP -`GET "/signalk/v1/api/resources/routes?bounds=r1f2r"` +``` +GET "/signalk/v1/api/resources/routes?geohash=r1f2r" + +GET "/signalk/v1/api/resources/routes?bounds=[138.23, -38.123, 139.76,-37.89]" -### Via a Delta +GET "/signalk/v1/api/resources/routes?distance=10000" +``` + +### Via Delta ```json { "requestId": "6b0e776f-811a-4b35-980e-b93405371bc5", "get": [{ "path": "resources.notes", - "params": { "bounds": "r1f2r" } + "params": { "geohash": "r1f2r" } + }] +} + +{ + "requestId": "6b0e776f-811a-4b35-980e-b93405371e25", + "get": [{ + "path": "resources.waypoints", + "params": { + "bounds": [138.23, -38.123, 139.76,-37.89] + } + }] +} + +{ + "requestId": "6b0e776f-811a-4b35-980e-b93405371bc5", + "get": [{ + "path": "resources.notes", + "params": { "distance": 10000 } }] } ``` @@ -71,7 +108,9 @@ You can specify the maximum number of resource entries that are returned by usin ### Via HTTP -`GET "/signalk/v1/api/resources/routes?maxcount=200"` +``` +GET "/signalk/v1/api/resources/routes?maxcount=100" +``` ### Via a Delta @@ -80,18 +119,31 @@ You can specify the maximum number of resource entries that are returned by usin "requestId": "6b0e776f-811a-4b35-980e-b93405371bc5", "get": [{ "path": "resources.notes", - "params": { "maxcount": 200 } + "params": { "maxcount": 100 } }] } ``` +_Note: The Delta response to a request where the snumber of returned resources has been capped at `maxcount` should include a `message` indicating this._ + +```json +{ + "requestId": "123345-23232-232323", + "state": "COMPLETED", + "statusCode": 200, + "message": "Maximum number of items returned." +} +``` + #### Implementation specific parameters Specific use cases may require a richer set of options to target the entries to be returned. In these cases implementors can provide their own parameters for use in conjunction with those defined above as part of their product / solution. ### Via HTTP -`GET "/signalk/v1/api/resources/routes?myparam=myparam_value&maxcount=150"` +``` +GET "/signalk/v1/api/resources/routes?myparam=myparam_value&maxcount=150" +``` ### Via a Delta @@ -101,8 +153,8 @@ Specific use cases may require a richer set of options to target the entries to "get": [{ "path": "resources.notes", "params": { - "bounds": "r1f2r", - "maxcount": 200 + "myparam": "myparam_value", + "maxcount": 150 } }] } @@ -322,7 +374,9 @@ _Note: The `context` attribute is not required when making Resource requests._ Send an HTTP DELETE request to the path of the resource. -`DELETE http://localhost:3000/signalk/v1/api/vessels/resources/notes/urn:mrn:signalk:uuid:36f9b6b5-959f-46a1-8a68-82159742aadd` +``` +DELETE http://localhost:3000/signalk/v1/api/vessels/resources/notes/urn:mrn:signalk:uuid:36f9b6b5-959f-46a1-8a68-82159742aadd +``` ### Via a Delta From c0e9fdaa8b6ace400e01eaa0ddeb97db224911b8 Mon Sep 17 00:00:00 2001 From: Adrian Panazzolo <38519157+panaaj@users.noreply.github.com> Date: Mon, 18 Mar 2019 13:49:36 +1030 Subject: [PATCH 04/10] updated `bounds` definitions and examples --- gitbook-docs/resources.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/gitbook-docs/resources.md b/gitbook-docs/resources.md index 4aaa65056..c6be3159c 100644 --- a/gitbook-docs/resources.md +++ b/gitbook-docs/resources.md @@ -55,10 +55,10 @@ You can request resources that fall within a bounded geographic area by using on Use the `geohash` parameter along with a __geohash__ to define the bounded area from within which resources will be returned. - __SW / NE coordinates__: -Use the `bounds` parameter to suppy an array `[x1,y1,x2,y2]` that defines the SW and NE corners of the bounded area from within which resources will be returned. +Use the `bounds` parameter to suppy an array `x1,y1,x2,y2` that defines the SW `x1,y1` and NE `x2,y2` corners of the bounded area from within which resources will be returned. - __Distance from vessel__: -Use the `distance` parameter to specify the number of meters from the vessel that the bounded area (square) from within which resources will be returned. +Use the `distance` parameter to specify the number of meters to the edge of a bounded area _(a square of which the vessel is at the center)_ from within which resources will be returned. _Examples:_ @@ -67,7 +67,7 @@ _Examples:_ ``` GET "/signalk/v1/api/resources/routes?geohash=r1f2r" -GET "/signalk/v1/api/resources/routes?bounds=[138.23, -38.123, 139.76,-37.89]" +GET "/signalk/v1/api/resources/routes?bounds=138.23,-38.123, 139.76,-37.89" GET "/signalk/v1/api/resources/routes?distance=10000" ``` @@ -88,7 +88,7 @@ GET "/signalk/v1/api/resources/routes?distance=10000" "get": [{ "path": "resources.waypoints", "params": { - "bounds": [138.23, -38.123, 139.76,-37.89] + "bounds": "138.23,-38.123,139.76,-37.89" } }] } From 18d746310155048e090e9c1395e9b7b36b1fd20f Mon Sep 17 00:00:00 2001 From: Adrian Panazzolo <38519157+panaaj@users.noreply.github.com> Date: Mon, 18 Mar 2019 15:38:14 +1030 Subject: [PATCH 05/10] Remove scenario of client supplied UUID in Creating Resource section --- gitbook-docs/resources.md | 113 +++++++++++--------------------------- 1 file changed, 33 insertions(+), 80 deletions(-) diff --git a/gitbook-docs/resources.md b/gitbook-docs/resources.md index c6be3159c..1e1f3e46a 100644 --- a/gitbook-docs/resources.md +++ b/gitbook-docs/resources.md @@ -164,33 +164,24 @@ GET "/signalk/v1/api/resources/routes?myparam=myparam_value&maxcount=150" ## CREATING a Resource Entry -_Note: The creation, update or deletion of a resource should trigger the relevent Delta UPDATE message._ +To create a resource a complete resource record is sent to the Signal K server via either an HTTP or Delta request. -### Via HTTP +A resource is identified by a __uuid__ which will be generated by the Signal K server and assigned to the resource entry. -__1. Where the server will generate the UUID of the new resource:__ +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": { ... }, + "value": { resource_data }, "source": "sourceId" } ``` -__2. Where the client will generate the UUID of the new resource:__ - -Send an HTTP PUT request to the appropriate resource path containing a payload of the following format: -```json -{ - "value": { - "my_uuid": { ... } - }, - "source": "sourceId" -} -``` +_Example:_ -_Example: Server creates resource uuid_ ```json POST http://localhost:3000/signalk/v1/api/vessels/resources/notes { @@ -208,27 +199,6 @@ POST http://localhost:3000/signalk/v1/api/vessels/resources/notes } ``` -_Example: Client creates resource uuid_ - -```json -PUT http://localhost:3000/signalk/v1/api/vessels/resources/notes -{ - "value": { - "urn:mrn:signalk:uuid:36f9b6b5-959f-46a1-8a68-82159742aadd": { - "position": { - "latitude": -35.025778007875, - "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. @@ -239,27 +209,15 @@ __1. Where the server will generate the UUID of the new resource:__ Send a PUT message to the appropriate resource path containing a payload of the following format: ```json { - "value": { ... }, - "path": "resources." -} -``` - -__2. Where the client will generate the UUID of the new resource:__ - -Send a PUT message to the appropriate resource path containing a payload of the following format: -```json -{ - "value": { - "my_uuid": { ... } - }, - "path": "resources." + "value": { resource_data }, + "path": "resources." } ``` _Note: The `context` attribute is not required when making Resource requests._ -_Example: Server creates resource uuid_ +_Example:_ ```json { @@ -279,39 +237,22 @@ _Example: Server creates resource uuid_ }] } ``` - -_Example: Client creates resource uuid_ - -```json -{ - "requestId": "6b0e776f-811a-4b35-980e-b93405371bc5", - "put": [{ - "path": "resources.notes", - "value": { - "urn:mrn:signalk:uuid:36f9b6b5-959f-46a1-8a68-82159742aadd": { - "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 with a payload of the following format: +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": { ... }, + "value": { resource_data }, "source": "sourceId" } ``` @@ -339,8 +280,8 @@ PUT http://localhost:3000/signalk/v1/api/vessels/resources/notes/urn:mrn:signalk Send a PUT message to the appropriate resource path containing a payload of the following format: ```json { - "value": { ... }, - "path": "resources.." + "value": { resource_data }, + "path": "resources.." } ``` @@ -369,11 +310,15 @@ _Note: The `context` attribute is not required when making Resource requests._ ## 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. ### Via HTTP -Send an HTTP DELETE request to the path of the resource. +Send an HTTP DELETE request to the path of the resource _(which includes the resource uuid)_. +_Example:_ ``` DELETE http://localhost:3000/signalk/v1/api/vessels/resources/notes/urn:mrn:signalk:uuid:36f9b6b5-959f-46a1-8a68-82159742aadd ``` @@ -382,8 +327,16 @@ DELETE http://localhost:3000/signalk/v1/api/vessels/resources/notes/urn:mrn:sign Send a PUT message to the appropriate resource path containing a payload with a value of `null`. +```json +{ + "value": null, + "path": "resources.." +} +``` + _Note: The `context` attribute is not required when making Resource requests._ +_Example:_ ```json { From 65f8d4d0bcdd83cb80ff393af3aa4ae9fe1ebbc8 Mon Sep 17 00:00:00 2001 From: Adrian Panazzolo <38519157+panaaj@users.noreply.github.com> Date: Sun, 24 Mar 2019 15:44:21 +1030 Subject: [PATCH 06/10] Updated params object format --- gitbook-docs/resources.md | 165 +++++++++++++++++++++----------------- 1 file changed, 91 insertions(+), 74 deletions(-) diff --git a/gitbook-docs/resources.md b/gitbook-docs/resources.md index 1e1f3e46a..03ad11cbb 100644 --- a/gitbook-docs/resources.md +++ b/gitbook-docs/resources.md @@ -43,11 +43,59 @@ As the number of entries within a specific resource group can be large, you can These parameters can be used individually or together to return the required resource entries. +### via HTTP +Parameters are specified as a query string _e.g. ../resources/routes?param1=value1¶m2=value2"_ + +### via Delta + +Parameters are specified within a `params` object in the __GET__ request. + +_Example_ ``` -GET "/signalk/v1/api/resources/routes?geohash=r1f2r&maxcount=200" +"get": [{ + "path": "resources.notes", + "params": { + "param1": value1, + "param2": value2 + } +}] +``` + +#### 1. Specify maximum number entries to return + +You can specify the maximum number of resource entries that are returned by using the `limit` parameter. + +### via HTTP + ``` +GET "/signalk/v1/api/resources/routes?limit=100" +``` -#### 1. Restrict by Bounded Area +### via Delta + +```json +{ + "requestId": "6b0e776f-811a-4b35-980e-b93405371ac5", + "get": [{ + "path": "resources.notes", + "params": { "limit": 100 } + }] +} +``` + +_Note: The Delta response to a request where the number of returned resources has been capped at `limit` should include a `message` indicating this._ + +```json +{ + "requestId": "123345-23232-232323", + "state": "COMPLETED", + "statusCode": 200, + "message": "Maximum number of items returned." +} +``` + + +#### 2. Restrict by Bounded Area You can request resources that fall within a bounded geographic area by using one of the following parameters: @@ -55,31 +103,37 @@ You can request resources that fall within a bounded geographic area by using on Use the `geohash` parameter along with a __geohash__ to define the bounded area from within which resources will be returned. - __SW / NE coordinates__: -Use the `bounds` parameter to suppy an array `x1,y1,x2,y2` that defines the SW `x1,y1` and NE `x2,y2` corners of the bounded area from within which resources will be returned. +Use the `geobounds` parameter to supply the coordinates `x1,y1,x2,y2` that define the SW `(x1,y1)` and NE `(x2,y2)` corners of the bounded area from within which resources will be returned. - __Distance from vessel__: -Use the `distance` parameter to specify the number of meters to the edge of a bounded area _(a square of which the vessel is at the center)_ from within which resources will be returned. +Use the `geobox` parameter to specify the radius _(in meters)_ of a square, with the vessel at the center, from within which resources will be returned. _Examples:_ -### Via HTTP +### via HTTP ``` GET "/signalk/v1/api/resources/routes?geohash=r1f2r" -GET "/signalk/v1/api/resources/routes?bounds=138.23,-38.123, 139.76,-37.89" +GET "/signalk/v1/api/resources/routes?geobounds=138.23,-38.123, 139.76,-37.89" + +GET "/signalk/v1/api/resources/routes?geobox=10000" -GET "/signalk/v1/api/resources/routes?distance=10000" +GET "/signalk/v1/api/resources/routes?geohash=r1f2r&limit=200" ``` -### Via Delta +### via Delta ```json { "requestId": "6b0e776f-811a-4b35-980e-b93405371bc5", "get": [{ "path": "resources.notes", - "params": { "geohash": "r1f2r" } + "params": { + "geo": { + "hash": "r1f2r" + } + } }] } @@ -88,73 +142,34 @@ GET "/signalk/v1/api/resources/routes?distance=10000" "get": [{ "path": "resources.waypoints", "params": { - "bounds": "138.23,-38.123,139.76,-37.89" + "geo": { + "bounds": [138.23,-38.123,139.76,-37.89] + } } }] } { - "requestId": "6b0e776f-811a-4b35-980e-b93405371bc5", + "requestId": "6b0e776f-811a-4b35-980e-b93405371b35", "get": [{ "path": "resources.notes", - "params": { "distance": 10000 } - }] -} -``` - -#### 2. Specify maximum number of returned entries - -You can specify the maximum number of resource entries that are returned by using the `maxcount` parameter. - -### Via HTTP - -``` -GET "/signalk/v1/api/resources/routes?maxcount=100" -``` - -### Via a Delta - -```json -{ - "requestId": "6b0e776f-811a-4b35-980e-b93405371bc5", - "get": [{ - "path": "resources.notes", - "params": { "maxcount": 100 } + "params": { + "geo": { + "box": 10000 + } + } }] } -``` - -_Note: The Delta response to a request where the snumber of returned resources has been capped at `maxcount` should include a `message` indicating this._ - -```json -{ - "requestId": "123345-23232-232323", - "state": "COMPLETED", - "statusCode": 200, - "message": "Maximum number of items returned." -} -``` - -#### Implementation specific parameters - -Specific use cases may require a richer set of options to target the entries to be returned. In these cases implementors can provide their own parameters for use in conjunction with those defined above as part of their product / solution. -### Via HTTP - -``` -GET "/signalk/v1/api/resources/routes?myparam=myparam_value&maxcount=150" -``` - -### Via a Delta - -```json { - "requestId": "6b0e776f-811a-4b35-980e-b93405371bc5", + "requestId": "6b0e776f-811a-4b35-980e-b93405371b45", "get": [{ "path": "resources.notes", "params": { - "myparam": "myparam_value", - "maxcount": 150 + "geo": { + "hash": "r1f2r" + }, + "limit": 100 } }] } @@ -170,12 +185,12 @@ A resource is identified by a __uuid__ which will be generated by the Signal K s The Signal K server will emit a Delta UPDATE message for the new resource upon success. -### Via HTTP +### via HTTP Send an HTTP POST request to the appropriate resource path containing a payload of the following format: ```json { - "value": { resource_data }, + "value": { }, "source": "sourceId" } ``` @@ -202,14 +217,14 @@ POST http://localhost:3000/signalk/v1/api/vessels/resources/notes 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 a Delta +### via Delta __1. Where the server will generate the UUID of the new resource:__ Send a PUT message to the appropriate resource path containing a payload of the following format: ```json { - "value": { resource_data }, + "value": { }, "path": "resources." } ``` @@ -247,12 +262,12 @@ 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 +### 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 }, + "value": { }, "source": "sourceId" } ``` @@ -275,12 +290,12 @@ PUT http://localhost:3000/signalk/v1/api/vessels/resources/notes/urn:mrn:signalk } ``` -### Via a Delta +### via Delta Send a PUT message to the appropriate resource path containing a payload of the following format: ```json { - "value": { resource_data }, + "value": { }, "path": "resources.." } ``` @@ -314,18 +329,20 @@ To delete a resource entry the appropriate HTTP or Delta request is made to the The Signal K server will emit a Delta UPDATE message for the deleted resource _(with a value of `null`)_ upon success. -### Via HTTP +__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 _(which includes the resource uuid)_. +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 +### via a Delta -Send a PUT message to the appropriate resource path containing a payload with a value of `null`. +Send a PUT message to the path of the resource to be removed with a value of `null`. ```json { From 49e11f3c573030c7195adc3c55911e48d98c0589 Mon Sep 17 00:00:00 2001 From: Adrian Panazzolo <38519157+panaaj@users.noreply.github.com> Date: Tue, 2 Apr 2019 13:32:22 +1030 Subject: [PATCH 07/10] Update HTTP parameters format --- gitbook-docs/resources.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/gitbook-docs/resources.md b/gitbook-docs/resources.md index 03ad11cbb..0e3c71751 100644 --- a/gitbook-docs/resources.md +++ b/gitbook-docs/resources.md @@ -100,26 +100,26 @@ _Note: The Delta response to a request where the number of returned resources ha You can request resources that fall within a bounded geographic area by using one of the following parameters: - __GeoHash__: -Use the `geohash` parameter along with a __geohash__ to define the bounded area from within which resources will be returned. +Use the `geo.hash` parameter along with a __geohash__ to define the bounded area from within which resources will be returned. - __SW / NE coordinates__: -Use the `geobounds` parameter to supply the coordinates `x1,y1,x2,y2` that define the SW `(x1,y1)` and NE `(x2,y2)` corners of the bounded area from within which resources will be returned. +Use the `geo.bounds` parameter to supply the coordinates `x1,y1,x2,y2` that define the SW `(x1,y1)` and NE `(x2,y2)` corners of the bounded area from within which resources will be returned. - __Distance from vessel__: -Use the `geobox` parameter to specify the radius _(in meters)_ of a square, with the vessel at the center, from within which resources will be returned. +Use the `geo.box` parameter to specify the radius _(in meters)_ of a square, with the vessel at the center, from within which resources will be returned. _Examples:_ ### via HTTP ``` -GET "/signalk/v1/api/resources/routes?geohash=r1f2r" +GET "/signalk/v1/api/resources/routes?geo.hash=r1f2r" -GET "/signalk/v1/api/resources/routes?geobounds=138.23,-38.123, 139.76,-37.89" +GET "/signalk/v1/api/resources/routes?geo.bounds=138.23,-38.123,139.76,-37.89" -GET "/signalk/v1/api/resources/routes?geobox=10000" +GET "/signalk/v1/api/resources/routes?geo.box=10000" -GET "/signalk/v1/api/resources/routes?geohash=r1f2r&limit=200" +GET "/signalk/v1/api/resources/routes?geo.hash=r1f2r&limit=200" ``` ### via Delta From 977d346d6513f646b9e42145fd52d2f0d608246b Mon Sep 17 00:00:00 2001 From: Adrian Panazzolo <38519157+panaaj@users.noreply.github.com> Date: Tue, 9 Apr 2019 09:32:12 +0930 Subject: [PATCH 08/10] Restructure & updated description text to better clarify the use of the `resources` path and identify the four resource types defined in the schema. --- gitbook-docs/resources.md | 38 ++++++++++++++++++++++++++++---------- 1 file changed, 28 insertions(+), 10 deletions(-) diff --git a/gitbook-docs/resources.md b/gitbook-docs/resources.md index 0e3c71751..354a60961 100644 --- a/gitbook-docs/resources.md +++ b/gitbook-docs/resources.md @@ -1,22 +1,38 @@ # Resources -Resources are collections of objects that are used to represent data that serves as additional information to aid with navigation, etc. +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. -Resources are: -- Usually persisted in a non-volatile data store _(i.e. not lost when server re-starts)_ -- Potentially large in number and / or record size +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 -- A top level path in the Signal K API: `/signalk/v1/api/resources/*` -Resource entries: -- Of a specific type are grouped under a specific path _i.e. `/signalk/v1/api/resources/waypoints`_ -- Are identified by a __uuid__. _e.g. `urn:mrn:signalk:uuid:36f9b6b5-959f-46a1-8a68-82159742aadd`_ +Resources are grouped under a specific path based on their type _i.e. `.../resources/waypoints`_ and can represent data that is hosted locally or provided via a service. -- Originating from other vessels will have a `$source` attribute that contains the id of the source vessel. +The Signal K specification defines the following resource group paths and associated schemas: +- __routes__: `.../resources/routes` +- __waypoints__: `.../resources/waypoints` +- __notes__: `.../resources/notes` +- __regions__: `.../resources/regions` -- May contain references to other resources in either the same or different group. _i.e. A route's `start` and `end` attribute contains a reference to a `waypoint` resource._ +Group paths under `.../resources/` should clearly identify the type of data hosted. +_e.g. `.../resources/weather`, `.../resources/video`_ + +Each resource entry within a group must be uniquely identified, this can be via a __name__ or __uuid__. + +_e.g. `.../resources/waypoints/urn:mrn:signalk:uuid:36f9b6b5-959f-46a1-8a68-82159742aadd`_ + +_e.g. `.../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 @@ -43,6 +59,8 @@ As the number of entries within a specific resource group can be large, you can These parameters can be used individually or together to return the required resource entries. +_Note: The ability to use parameters to restrict the returned entries will be determined by the provider of the resource._ + ### via HTTP Parameters are specified as a query string _e.g. ../resources/routes?param1=value1¶m2=value2"_ From f723d9eea98d73eff6de82899895fab7d05dc4e4 Mon Sep 17 00:00:00 2001 From: Adrian Panazzolo <38519157+panaaj@users.noreply.github.com> Date: Sat, 22 Jun 2019 16:41:15 +0930 Subject: [PATCH 09/10] Introduction updates. --- gitbook-docs/resources.md | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/gitbook-docs/resources.md b/gitbook-docs/resources.md index 354a60961..2eb4dfd71 100644 --- a/gitbook-docs/resources.md +++ b/gitbook-docs/resources.md @@ -8,23 +8,24 @@ Resource data can differ from _sensor_ data in the following ways: - Able to be created, updated and deleted by both applications and server processes -Resources are grouped under a specific path based on their type _i.e. `.../resources/waypoints`_ and can represent data that is hosted locally or provided via a service. +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` -The Signal K specification defines the following resource group paths and associated schemas: -- __routes__: `.../resources/routes` -- __waypoints__: `.../resources/waypoints` -- __notes__: `.../resources/notes` -- __regions__: `.../resources/regions` -Group paths under `.../resources/` should clearly identify the type of data hosted. +Additional resource types can be defined under `/signalk/v1/api/resources/`, the assigned path should clearly identify the type of data hosted. -_e.g. `.../resources/weather`, `.../resources/video`_ +_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__. -_e.g. `.../resources/waypoints/urn:mrn:signalk:uuid:36f9b6b5-959f-46a1-8a68-82159742aadd`_ +``` +signalk/v1/api/resources/waypoints/urn:mrn:signalk:uuid:36f9b6b5-959f-46a1-8a68-82159742aadd_ -_e.g. `.../resources/video/bowCamera`_ +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. @@ -237,8 +238,6 @@ value, the server should respond with a 400 (Bad Request) HTTP status code. ### via Delta -__1. Where the server will generate the UUID of the new resource:__ - Send a PUT message to the appropriate resource path containing a payload of the following format: ```json { From 18485e7bb7dab0705de264914c33a50a55c6b79b Mon Sep 17 00:00:00 2001 From: Adrian Panazzolo <38519157+panaaj@users.noreply.github.com> Date: Sat, 22 Jun 2019 16:43:26 +0930 Subject: [PATCH 10/10] Remove filtering returned entires section. --- gitbook-docs/resources.md | 143 +------------------------------------- 1 file changed, 1 insertion(+), 142 deletions(-) diff --git a/gitbook-docs/resources.md b/gitbook-docs/resources.md index 2eb4dfd71..4709f4200 100644 --- a/gitbook-docs/resources.md +++ b/gitbook-docs/resources.md @@ -45,7 +45,7 @@ See [Request/Response](request_response.md) for more details on request/response --- -## Getting Resource Entries +## GETTING Resource Entries Resource entries are returned when either an HTTP or Delta __GET__ request is made to a resource path. @@ -53,147 +53,6 @@ Resource entries are returned when either an HTTP or Delta __GET__ request is ma - 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`_ - -### Restricting the number of returned entries - -As the number of entries within a specific resource group can be large, you can provide parameters with your request to limit the number of entries returned. - -These parameters can be used individually or together to return the required resource entries. - -_Note: The ability to use parameters to restrict the returned entries will be determined by the provider of the resource._ - -### via HTTP -Parameters are specified as a query string _e.g. ../resources/routes?param1=value1¶m2=value2"_ - -### via Delta - -Parameters are specified within a `params` object in the __GET__ request. - -_Example_ -``` -"get": [{ - "path": "resources.notes", - "params": { - "param1": value1, - "param2": value2 - } -}] -``` - -#### 1. Specify maximum number entries to return - -You can specify the maximum number of resource entries that are returned by using the `limit` parameter. - -### via HTTP - -``` -GET "/signalk/v1/api/resources/routes?limit=100" -``` - -### via Delta - -```json -{ - "requestId": "6b0e776f-811a-4b35-980e-b93405371ac5", - "get": [{ - "path": "resources.notes", - "params": { "limit": 100 } - }] -} -``` - -_Note: The Delta response to a request where the number of returned resources has been capped at `limit` should include a `message` indicating this._ - -```json -{ - "requestId": "123345-23232-232323", - "state": "COMPLETED", - "statusCode": 200, - "message": "Maximum number of items returned." -} -``` - - -#### 2. Restrict by Bounded Area - -You can request resources that fall within a bounded geographic area by using one of the following parameters: - -- __GeoHash__: -Use the `geo.hash` parameter along with a __geohash__ to define the bounded area from within which resources will be returned. - -- __SW / NE coordinates__: -Use the `geo.bounds` parameter to supply the coordinates `x1,y1,x2,y2` that define the SW `(x1,y1)` and NE `(x2,y2)` corners of the bounded area from within which resources will be returned. - -- __Distance from vessel__: -Use the `geo.box` parameter to specify the radius _(in meters)_ of a square, with the vessel at the center, from within which resources will be returned. - -_Examples:_ - -### via HTTP - -``` -GET "/signalk/v1/api/resources/routes?geo.hash=r1f2r" - -GET "/signalk/v1/api/resources/routes?geo.bounds=138.23,-38.123,139.76,-37.89" - -GET "/signalk/v1/api/resources/routes?geo.box=10000" - -GET "/signalk/v1/api/resources/routes?geo.hash=r1f2r&limit=200" -``` - -### via Delta - -```json -{ - "requestId": "6b0e776f-811a-4b35-980e-b93405371bc5", - "get": [{ - "path": "resources.notes", - "params": { - "geo": { - "hash": "r1f2r" - } - } - }] -} - -{ - "requestId": "6b0e776f-811a-4b35-980e-b93405371e25", - "get": [{ - "path": "resources.waypoints", - "params": { - "geo": { - "bounds": [138.23,-38.123,139.76,-37.89] - } - } - }] -} - -{ - "requestId": "6b0e776f-811a-4b35-980e-b93405371b35", - "get": [{ - "path": "resources.notes", - "params": { - "geo": { - "box": 10000 - } - } - }] -} - -{ - "requestId": "6b0e776f-811a-4b35-980e-b93405371b45", - "get": [{ - "path": "resources.notes", - "params": { - "geo": { - "hash": "r1f2r" - }, - "limit": 100 - } - }] -} -``` - --- ## CREATING a Resource Entry