From 6f02c447dbb9634db8b8a9908d7c560189fe74a7 Mon Sep 17 00:00:00 2001 From: Scott Bender Date: Thu, 20 Sep 2018 09:43:18 -0400 Subject: [PATCH 01/10] feature: PUT Requests --- gitbook-docs/SUMMARY.md | 1 + gitbook-docs/put.md | 141 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 142 insertions(+) create mode 100644 gitbook-docs/put.md diff --git a/gitbook-docs/SUMMARY.md b/gitbook-docs/SUMMARY.md index 7fe7616cb..110faf90c 100644 --- a/gitbook-docs/SUMMARY.md +++ b/gitbook-docs/SUMMARY.md @@ -16,6 +16,7 @@ * [Subscription Protocol](subscription_protocol.md) * [Discovery & Connection Establishment](connection.md) * [Notifications](notifications.md) + * [PUT Requests](put.md) * [How Can I Help?](how_to_help.md) * [Appendix A: Keys Reference (Vessel)](vesselsBranch.md) * [Appendix B: Keys Reference (Others)](otherBranches.md) diff --git a/gitbook-docs/put.md b/gitbook-docs/put.md new file mode 100644 index 000000000..4629f7be0 --- /dev/null +++ b/gitbook-docs/put.md @@ -0,0 +1,141 @@ +# PUT Requests + +PUT requestes are sent to a server to request a change to a value. For example, a client would use PUT to switch the anchor light on or off, change the heading of the autopilot, or set position of the anchor. + +## Making a request to change a value +To change a value, a PUT request should be sent via HTTP or using a SignalK 'put' delta. + +The "source" field is optional. If a request is sent without the source and their is more than one source for the value, that will result in a 400 HTTP error response. + +### via http +``` +PUT http://localhost:3000/signalk/v1/api/vessels/self/steering/autopilot/target/headingTrue +{ + "value" = 1.52, + "source": "actisense.204", +} +``` + +### via a delta +``` +{ + "context": "vessels.self", + "put": { + "path": "steering.autopilot.target.headingTrue", + "source": "actisense.204", + "value": 1.52 + } +} +``` + +## The response to a request to change a value + +The possible responses the server can make to this request. +* Permission denied +* The request is not supported +* There was an error processing the request +* The request was processed and the value has been changed +* The request has been received and is being worked on asynchronously + +I will cover these for HTTP methods since there is no defined way to do request/response over ws or other protocols. + +### HTTP response for permission denied + +HTTP response code 403 (Forbidden) + +### HTTP response when the request is not supported + +HTTP response code 405 (Method Not Allowed) + +### HTTP response when there is an error processing the request + +HTTP response codes: + 400 (something wrong with the client's request) + 502 (something went wrong carrying out the request on the server side) + 504 (timeout on the server side trying to carry out the request + +JSON response body: +``` +{ + "state": "COMPLETED", + "message": "Unable to reach device" +} +``` + +### HTTP Response to a successful PUT request + +HTTP response code 200 (OK) +JSON response body: +``` +{ + "state": "COMPLETED", +} +``` + +### HTTP Response to a request that is being worked on asynchronously + +The response in this case includes an optional `href` that can be used to check the status of the request. + +HTTP response code 202 (Accepted) +JSON response body: +``` +{ + "state":"PENDING", + "action": { + "id":12567, + "href": "/signalk/v1/api/actions/12567" + } +} +``` + +#### Response to `/signalk/v1/api/actions/12567` when the request has completed successfully + +``` +{ + "context" : "vessels.self", + "path" : "steering.autopilot.target.headingTrue", + "source": "actisense.204", + "user": "john@smith.com", + "requestedValue" : 1.57, + "startTime" : "2018-02-27T20:59:21.868Z", + "id" : 12567, + "endTime" : "2018-02-27T20:59:41.871Z", + "state": "COMPLETED" + "result" : "SUCCESS" +} +``` + +#### Response to `/signalk/v1/api/actions/12567` when the request has failed + +``` +{ + "context" : "vessels.self", + "path" : "steering.autopilot.target.headingTrue", + "source": "actisense.204", + "user": "john@smith.com", + "requestedValue" : 1.57, + "startTime" : "2018-02-27T20:59:21.868Z", + "id" : 12567, + "endTime" : "2018-02-27T20:59:41.871Z", + "state": "COMPLETED" + "result" : "FAILURE", + "message": "Unable to reach device" +} +``` + +#### Response to `/signalk/v1/api/actions/12567` when the request is pending +(note that percentComplete is optional) +``` +{ + "context" : "vessels.self", + "path" : "steering.autopilot.target.headingTrue", + "source": "actisense.204", + "user": "john@smith.com", + "requestedValue" : 1.57, + "startTime" : "2018-02-27T20:59:21.868Z", + "id" : 12567, + "state": "PENDING", + "percentComplete": 0.45 +} +``` + From 7d08997b680e6843f6b1cc394bf759b1a56690ae Mon Sep 17 00:00:00 2001 From: Scott Bender Date: Thu, 20 Sep 2018 15:12:14 -0400 Subject: [PATCH 02/10] docs: sync up with request/response PR --- gitbook-docs/put.md | 43 +++++++++---------------------------------- 1 file changed, 9 insertions(+), 34 deletions(-) diff --git a/gitbook-docs/put.md b/gitbook-docs/put.md index 4629f7be0..ec20eba89 100644 --- a/gitbook-docs/put.md +++ b/gitbook-docs/put.md @@ -2,6 +2,8 @@ PUT requestes are sent to a server to request a change to a value. For example, a client would use PUT to switch the anchor light on or off, change the heading of the autopilot, or set position of the anchor. +See [Request/Response](request_response.md) for more details on request/response in Signal K. + ## Making a request to change a value To change a value, a PUT request should be sent via HTTP or using a SignalK 'put' delta. @@ -27,38 +29,14 @@ PUT http://localhost:3000/signalk/v1/api/vessels/self/steering/autopilot/target/ } } ``` +### HTTP Response when there's an error -## The response to a request to change a value - -The possible responses the server can make to this request. -* Permission denied -* The request is not supported -* There was an error processing the request -* The request was processed and the value has been changed -* The request has been received and is being worked on asynchronously - -I will cover these for HTTP methods since there is no defined way to do request/response over ws or other protocols. - -### HTTP response for permission denied - -HTTP response code 403 (Forbidden) - -### HTTP response when the request is not supported - -HTTP response code 405 (Method Not Allowed) - -### HTTP response when there is an error processing the request - -HTTP response codes: - 400 (something wrong with the client's request) - 502 (something went wrong carrying out the request on the server side) - 504 (timeout on the server side trying to carry out the request - +HTTP response code 403: JSON response body: ``` { "state": "COMPLETED", - "message": "Unable to reach device" + "result": "PERMISSIONDENIED" } ``` @@ -69,6 +47,7 @@ JSON response body: ``` { "state": "COMPLETED", + "result": "SUCCESS" } ``` @@ -80,15 +59,11 @@ HTTP response code 202 (Accepted) JSON response body: ``` { - "state":"PENDING", - "action": { - "id":12567, - "href": "/signalk/v1/api/actions/12567" - } + "href": "/signalk/v1/actions/12567" } ``` -#### Response to `/signalk/v1/api/actions/12567` when the request has completed successfully +#### Response to `/signalk/v1/actions/12567` when the request has completed successfully ``` { @@ -105,7 +80,7 @@ JSON response body: } ``` -#### Response to `/signalk/v1/api/actions/12567` when the request has failed +#### Response to `/signalk/v1/actions/12567` when the request has failed ``` { From d2ff96121b350100a284b96f2fb2453ac8e0aaed Mon Sep 17 00:00:00 2001 From: Scott Bender Date: Fri, 28 Sep 2018 14:59:46 -0400 Subject: [PATCH 03/10] docs: change result in examples to be HTTP codes --- gitbook-docs/put.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/gitbook-docs/put.md b/gitbook-docs/put.md index ec20eba89..b83da34b2 100644 --- a/gitbook-docs/put.md +++ b/gitbook-docs/put.md @@ -36,7 +36,7 @@ JSON response body: ``` { "state": "COMPLETED", - "result": "PERMISSIONDENIED" + "result": 403 } ``` @@ -47,7 +47,7 @@ JSON response body: ``` { "state": "COMPLETED", - "result": "SUCCESS" + "result": 202 } ``` @@ -76,7 +76,7 @@ JSON response body: "id" : 12567, "endTime" : "2018-02-27T20:59:41.871Z", "state": "COMPLETED" - "result" : "SUCCESS" + "result" : 200 } ``` @@ -93,7 +93,7 @@ JSON response body: "id" : 12567, "endTime" : "2018-02-27T20:59:41.871Z", "state": "COMPLETED" - "result" : "FAILURE", + "result" : 502, "message": "Unable to reach device" } ``` From 777b955dbb814271b30008977e7c6428ee023034 Mon Sep 17 00:00:00 2001 From: Scott Bender Date: Fri, 28 Sep 2018 20:56:20 -0400 Subject: [PATCH 04/10] docs: updated to reflect the latest request/response document --- gitbook-docs/put.md | 42 +++++++++++++++++++----------------------- 1 file changed, 19 insertions(+), 23 deletions(-) diff --git a/gitbook-docs/put.md b/gitbook-docs/put.md index b83da34b2..6792fa563 100644 --- a/gitbook-docs/put.md +++ b/gitbook-docs/put.md @@ -22,6 +22,7 @@ PUT http://localhost:3000/signalk/v1/api/vessels/self/steering/autopilot/target/ ``` { "context": "vessels.self", + "correlationId": "184743-434373-348483", "put": { "path": "steering.autopilot.target.headingTrue", "source": "actisense.204", @@ -68,15 +69,13 @@ JSON response body: ``` { "context" : "vessels.self", - "path" : "steering.autopilot.target.headingTrue", - "source": "actisense.204", - "user": "john@smith.com", - "requestedValue" : 1.57, - "startTime" : "2018-02-27T20:59:21.868Z", - "id" : 12567, - "endTime" : "2018-02-27T20:59:41.871Z", "state": "COMPLETED" - "result" : 200 + "result" : 200, + "put": { + "path" : "steering.autopilot.target.headingTrue", + "source": "actisense.204", + "value" : 1.57 + } } ``` @@ -85,16 +84,14 @@ JSON response body: ``` { "context" : "vessels.self", - "path" : "steering.autopilot.target.headingTrue", - "source": "actisense.204", - "user": "john@smith.com", - "requestedValue" : 1.57, - "startTime" : "2018-02-27T20:59:21.868Z", - "id" : 12567, - "endTime" : "2018-02-27T20:59:41.871Z", "state": "COMPLETED" "result" : 502, - "message": "Unable to reach device" + "message": "Unable to reach device", + "put": { + "path" : "steering.autopilot.target.headingTrue", + "source": "actisense.204", + "value" : 1.57, + } } ``` @@ -103,14 +100,13 @@ JSON response body: ``` { "context" : "vessels.self", - "path" : "steering.autopilot.target.headingTrue", - "source": "actisense.204", - "user": "john@smith.com", - "requestedValue" : 1.57, - "startTime" : "2018-02-27T20:59:21.868Z", - "id" : 12567, "state": "PENDING", - "percentComplete": 0.45 + "percentComplete": 0.45, + "put": { + "path" : "steering.autopilot.target.headingTrue", + "source": "actisense.204", + "value" : 1.57 + } } ``` From fd8f0b3c106b2494629969dbdccfc6748837ebd7 Mon Sep 17 00:00:00 2001 From: Scott Bender Date: Sat, 29 Sep 2018 21:57:37 -0400 Subject: [PATCH 05/10] docs: remove details about the put request from the response --- gitbook-docs/put.md | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/gitbook-docs/put.md b/gitbook-docs/put.md index 6792fa563..75c108f7f 100644 --- a/gitbook-docs/put.md +++ b/gitbook-docs/put.md @@ -71,11 +71,6 @@ JSON response body: "context" : "vessels.self", "state": "COMPLETED" "result" : 200, - "put": { - "path" : "steering.autopilot.target.headingTrue", - "source": "actisense.204", - "value" : 1.57 - } } ``` @@ -87,11 +82,6 @@ JSON response body: "state": "COMPLETED" "result" : 502, "message": "Unable to reach device", - "put": { - "path" : "steering.autopilot.target.headingTrue", - "source": "actisense.204", - "value" : 1.57, - } } ``` @@ -102,11 +92,6 @@ JSON response body: "context" : "vessels.self", "state": "PENDING", "percentComplete": 0.45, - "put": { - "path" : "steering.autopilot.target.headingTrue", - "source": "actisense.204", - "value" : 1.57 - } } ``` From 61ba8085f388b080782742420c5d2a4a709905a6 Mon Sep 17 00:00:00 2001 From: Tim Mathews Date: Wed, 3 Oct 2018 15:14:28 -0400 Subject: [PATCH 06/10] Spelling --- gitbook-docs/put.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/gitbook-docs/put.md b/gitbook-docs/put.md index 75c108f7f..da70f52d0 100644 --- a/gitbook-docs/put.md +++ b/gitbook-docs/put.md @@ -1,11 +1,11 @@ # PUT Requests -PUT requestes are sent to a server to request a change to a value. For example, a client would use PUT to switch the anchor light on or off, change the heading of the autopilot, or set position of the anchor. +PUT requests are sent to a server to request a change to a value. For example, a client would use PUT to switch the anchor light on or off, change the heading of the autopilot, or set position of the anchor. See [Request/Response](request_response.md) for more details on request/response in Signal K. ## Making a request to change a value -To change a value, a PUT request should be sent via HTTP or using a SignalK 'put' delta. +To change a value, a PUT request should be sent via HTTP or using a Signal K 'put' delta. The "source" field is optional. If a request is sent without the source and their is more than one source for the value, that will result in a 400 HTTP error response. From 56160a54f7850d376ad83c2a0390cdea06bd3395 Mon Sep 17 00:00:00 2001 From: Tim Mathews Date: Wed, 3 Oct 2018 17:13:47 -0400 Subject: [PATCH 07/10] Formatting - Line width - Fixed some JSON typos --- gitbook-docs/put.md | 68 ++++++++++++++++++++++++++------------------- 1 file changed, 39 insertions(+), 29 deletions(-) diff --git a/gitbook-docs/put.md b/gitbook-docs/put.md index da70f52d0..847f5592e 100644 --- a/gitbook-docs/put.md +++ b/gitbook-docs/put.md @@ -1,25 +1,28 @@ # PUT Requests -PUT requests are sent to a server to request a change to a value. For example, a client would use PUT to switch the anchor light on or off, change the heading of the autopilot, or set position of the anchor. +PUT requests are sent to a server to request a change to a value. For example, a client would use PUT to switch the +anchor light on or off, change the heading of the autopilot, or set position of the anchor. See [Request/Response](request_response.md) for more details on request/response in Signal K. -## Making a request to change a value -To change a value, a PUT request should be sent via HTTP or using a Signal K 'put' delta. +## Making a Request to Change a Value -The "source" field is optional. If a request is sent without the source and their is more than one source for the value, that will result in a 400 HTTP error response. +To change a value, a PUT request should be sent via HTTP or using a Signal K __put__ delta. -### via http +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 HTTP ``` PUT http://localhost:3000/signalk/v1/api/vessels/self/steering/autopilot/target/headingTrue { - "value" = 1.52, + "value": 1.52, "source": "actisense.204", } ``` -### via a delta -``` +### Via a Delta +```json { "context": "vessels.self", "correlationId": "184743-434373-348483", @@ -30,68 +33,75 @@ PUT http://localhost:3000/signalk/v1/api/vessels/self/steering/autopilot/target/ } } ``` -### HTTP Response when there's an error -HTTP response code 403: +### HTTP Error Response + +HTTP response code 403 (Forbidden) + JSON response body: -``` +```json { "state": "COMPLETED", "result": 403 } ``` -### HTTP Response to a successful PUT request +### HTTP Success Response HTTP response code 200 (OK) + JSON response body: -``` +```json { "state": "COMPLETED", - "result": 202 + "result": 200 } ``` -### HTTP Response to a request that is being worked on asynchronously +### HTTP Success Response Indicating a Long Running Task The response in this case includes an optional `href` that can be used to check the status of the request. HTTP response code 202 (Accepted) + JSON response body: -``` +```json { "href": "/signalk/v1/actions/12567" } ``` -#### Response to `/signalk/v1/actions/12567` when the request has completed successfully +A client may periodically GET the URL provided above to check the status of the request. -``` +#### Response Indicating Successful Completion + +```json { - "context" : "vessels.self", + "context": "vessels.self", "state": "COMPLETED" - "result" : 200, + "result": 200, } ``` -#### Response to `/signalk/v1/actions/12567` when the request has failed +#### Response Indicating Failure -``` +```json { - "context" : "vessels.self", + "context": "vessels.self", "state": "COMPLETED" - "result" : 502, + "result": 502, "message": "Unable to reach device", } ``` -#### Response to `/signalk/v1/api/actions/12567` when the request is pending -(note that percentComplete is optional) -``` +#### Response Indicating Process is in Progress + +_Note:_ `percentComplete` is optional + +```json { - "context" : "vessels.self", + "context": "vessels.self", "state": "PENDING", "percentComplete": 0.45, } ``` - From ef7c81c1b66751be7b263197ef80cb5205f13402 Mon Sep 17 00:00:00 2001 From: Scott Bender Date: Wed, 3 Oct 2018 17:40:51 -0400 Subject: [PATCH 08/10] change percentComplete to progress, provide definition --- gitbook-docs/put.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/gitbook-docs/put.md b/gitbook-docs/put.md index 847f5592e..ff869ed49 100644 --- a/gitbook-docs/put.md +++ b/gitbook-docs/put.md @@ -96,12 +96,12 @@ A client may periodically GET the URL provided above to check the status of the #### Response Indicating Process is in Progress -_Note:_ `percentComplete` is optional +_Note:_ `progress` is optional and is specified as a ratio (a number from zero to one) ```json { "context": "vessels.self", "state": "PENDING", - "percentComplete": 0.45, + "progress": 0.45, } ``` From a96aadd15cfb2ea835a891c016373483fade6b08 Mon Sep 17 00:00:00 2001 From: Scott Bender Date: Wed, 3 Oct 2018 18:14:23 -0400 Subject: [PATCH 09/10] Rename `result` to `statusCode` --- gitbook-docs/put.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/gitbook-docs/put.md b/gitbook-docs/put.md index ff869ed49..e5a2a956e 100644 --- a/gitbook-docs/put.md +++ b/gitbook-docs/put.md @@ -42,7 +42,7 @@ JSON response body: ```json { "state": "COMPLETED", - "result": 403 + "statusCode": 403 } ``` @@ -54,7 +54,7 @@ JSON response body: ```json { "state": "COMPLETED", - "result": 200 + "statusCode": 200 } ``` @@ -67,6 +67,7 @@ HTTP response code 202 (Accepted) JSON response body: ```json { + "state": "PENDING", "href": "/signalk/v1/actions/12567" } ``` @@ -79,7 +80,7 @@ A client may periodically GET the URL provided above to check the status of the { "context": "vessels.self", "state": "COMPLETED" - "result": 200, + "statusCode": 200, } ``` @@ -89,7 +90,7 @@ A client may periodically GET the URL provided above to check the status of the { "context": "vessels.self", "state": "COMPLETED" - "result": 502, + "statusCode": 502, "message": "Unable to reach device", } ``` From 823324b56061614a75e2bb41aefe543a67922fad Mon Sep 17 00:00:00 2001 From: Scott Bender Date: Wed, 17 Oct 2018 13:47:25 -0400 Subject: [PATCH 10/10] fix: json syntax --- gitbook-docs/put.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/gitbook-docs/put.md b/gitbook-docs/put.md index e5a2a956e..603b18c33 100644 --- a/gitbook-docs/put.md +++ b/gitbook-docs/put.md @@ -79,7 +79,7 @@ A client may periodically GET the URL provided above to check the status of the ```json { "context": "vessels.self", - "state": "COMPLETED" + "state": "COMPLETED", "statusCode": 200, } ``` @@ -89,7 +89,7 @@ A client may periodically GET the URL provided above to check the status of the ```json { "context": "vessels.self", - "state": "COMPLETED" + "state": "COMPLETED", "statusCode": 502, "message": "Unable to reach device", } @@ -103,6 +103,6 @@ _Note:_ `progress` is optional and is specified as a ratio (a number from zero t { "context": "vessels.self", "state": "PENDING", - "progress": 0.45, + "progress": 0.45 } ```