{"action":"created","issue":{"url":"https://api.github.com/repos/SignalK/specification/issues/442","repository_url":"https://api.github.com/repos/SignalK/specification","labels_url":"https://api.github.com/repos/SignalK/specification/issues/442/labels{/name}","comments_url":"https://api.github.com/repos/SignalK/specification/issues/442/comments","events_url":"https://api.github.com/repos/SignalK/specification/issues/442/events","html_url":"https://github.com/SignalK/specification/issues/442","id":301074878,"number":442,"title":"RFC 0010: Actions (PUT/POST)","user":{"login":"sbender9","id":7853683,"avatar_url":"https://avatars3.githubusercontent.com/u/7853683?v=4","gravatar_id":"","url":"https://api.github.com/users/sbender9","html_url":"https://github.com/sbender9","followers_url":"https://api.github.com/users/sbender9/followers","following_url":"https://api.github.com/users/sbender9/following{/other_user}","gists_url":"https://api.github.com/users/sbender9/gists{/gist_id}","starred_url":"https://api.github.com/users/sbender9/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/sbender9/subscriptions","organizations_url":"https://api.github.com/users/sbender9/orgs","repos_url":"https://api.github.com/users/sbender9/repos","events_url":"https://api.github.com/users/sbender9/events{/privacy}","received_events_url":"https://api.github.com/users/sbender9/received_events","type":"User","site_admin":false},"labels":[{"id":451623461,"url":"https://api.github.com/repos/SignalK/specification/labels/RFC","name":"RFC","color":"38d14c","default":false}],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":12,"created_at":"2018-02-28T15:46:19Z","updated_at":"2018-03-02T15:42:20Z","closed_at":null,"author_association":"MEMBER","body":"RFC 0010: Actions (PUT/POST)\r\n\r\n# Summary\r\n[summary]: #summary\r\n\r\nWe do not currently detail the way to take actions to control things on a boat. There should be a well defined way to do things like turn lights on and off and control an autopilot, etc.\r\n\r\n# Motivation\r\n[motivation]: #motivation\r\n\r\nThis is currently being done in proprietary ways making it difficult for app developers to add support. 'update' deltas are one way this could be done and that has been proposed in the past. That does not work because displays and devices need to be able to tell the difference between a request to change the state of thing and an update of the current state.\r\n\r\n# Detailed design\r\n[design]: #detailed-design\r\n\r\nThere has been some discussion already about the exact methods used to do this. PUT/POST over HTTP and/or put deltas over ws. I'm just going to use the word PUT for now here.\r\n\r\n## Making a request to change a value\r\nTo change a value, a PUT request should be sent via HTTP or using a SignalK 'put' delta.\r\n\r\n### via http\r\n```\r\nPUT http://localhost:3000/signalk/v1/api/vessels/self/steering/autopilot/target/headingTrue\r\n{\r\n  \"value\" = 1.52\r\n}\r\n```\r\n\r\n### via a delta\r\n```\r\n{\r\n  \"context\": \"vessels.self\",\r\n  \"put\": {\r\n    \"path\": \"steering.autopilot.target.headingTrue\",\r\n    \"value\": 1.52\r\n  }\r\n}\r\n```\r\n\r\n## The response to a request to change a value\r\n\r\nThe possible responses the server can make to this request.\r\n* Permission denied\r\n* The request is not supported\r\n* There was an error processing the request\r\n* The request was processed and the value has been changed\r\n* The request has been received and is being worked on asynchronously\r\n\r\nI will cover these for HTTP methods since there is no defined way to do request/response over ws or other protocols.\r\n\r\n### HTTP response for permission denied\r\n\r\nHTTP response code 403 (Forbidden)\r\n\r\n### HTTP response when the request is not supported\r\n\r\nHTTP response code 405 (Method Not Allowed)\r\n\r\n### HTTP response when there is an error processing the request\r\n\r\nHTTP response code 200 (OK)\r\nJSON response body:\r\n```\r\n{\r\n  \"state\": \"COMPLETED\",\r\n  \"result\": \"FAILURE\",\r\n  \"message\": \"Unable to reach device\"\r\n}\r\n```\r\n\r\n### HTTP Response to a successful PUT request\r\n\r\nHTTP response code 200 (OK)\r\nJSON response body:\r\n```\r\n{\r\n  \"state\": \"COMPLETED\",\r\n  \"result\": \"SUCCESS\"\r\n}\r\n```\r\n\r\n### HTTP Response to a request that is being worked on asynchronously\r\n\r\nThe response in this case includes an optional `href` that can be used to check the status of the request.\r\n\r\nHTTP response code 202 (Accepted)\r\nJSON response body:\r\n```\r\n{\r\n  \"state\":\"PENDING\",\r\n  \"action\": {\r\n    \"id\":12567,\r\n    \"href\": \"/signalk/v1/api/actions/12567\"\r\n   }\r\n}\r\n```\r\n\r\n#### Response to `/signalk/v1/api/actions/12567` when the request has completed successfully \r\n\r\n```\r\n{\r\n   \"context\" : \"vessels.self\",\r\n   \"path\" : \"steering.autopilot.target.headingTrue\",\r\n   \"user\": \"john@smith.com\",\r\n   \"requestedValue\" : 1.57,\r\n   \"start-time\" : \"2018-02-27T20:59:21.868Z\",\r\n   \"id\" : 12567,\r\n   \"end-time\" : \"2018-02-27T20:59:41.871Z\",\r\n   \"state\": \"COMPLETED\"\r\n   \"result\" : \"SUCCESS\"\r\n}\r\n```\r\n\r\n#### Response to `/signalk/v1/api/actions/12567` when the request has failed\r\n\r\n```\r\n{\r\n   \"context\" : \"vessels.self\",\r\n   \"path\" : \"steering.autopilot.target.headingTrue\",\r\n   \"user\": \"john@smith.com\",\r\n   \"requestedValue\" : 1.57,\r\n   \"start-time\" : \"2018-02-27T20:59:21.868Z\",\r\n   \"id\" : 12567,\r\n   \"end-time\" : \"2018-02-27T20:59:41.871Z\",\r\n   \"state\": \"COMPLETED\"\r\n   \"result\" : \"FAILURE\",\r\n   \"message\": \"Unable to reach device\"\r\n}\r\n```\r\n\r\n#### Response to `/signalk/v1/api/actions/12567` when the request is pending\r\n(note that percentComplete is optional)\r\n```\r\n{\r\n   \"context\" : \"vessels.self\",\r\n   \"path\" : \"steering.autopilot.target.headingTrue\",\r\n   \"user\": \"john@smith.com\",\r\n   \"requestedValue\" : 1.57,\r\n   \"start-time\" : \"2018-02-27T20:59:21.868Z\",\r\n   \"id\" : 12567,\r\n   \"state\": \"PENDING\",\r\n   \"percentComplete\": 0.45\r\n}\r\n```\r\n\r\n# Unresolved questions\r\n[unresolved]: #unresolved-questions\r\n\r\nIt is not clear how to handle this with protocols like WS, TCP, etc. I propose that at least initially, the client will assume that the request is \"PENDING\" and watch for a delta update of the value to confirm that it was changed. "},"comment":{"url":"https://api.github.com/repos/SignalK/specification/issues/comments/369956885","html_url":"https://github.com/SignalK/specification/issues/442#issuecomment-369956885","issue_url":"https://api.github.com/repos/SignalK/specification/issues/442","id":369956885,"user":{"login":"tkurki","id":1049678,"avatar_url":"https://avatars3.githubusercontent.com/u/1049678?v=4","gravatar_id":"","url":"https://api.github.com/users/tkurki","html_url":"https://github.com/tkurki","followers_url":"https://api.github.com/users/tkurki/followers","following_url":"https://api.github.com/users/tkurki/following{/other_user}","gists_url":"https://api.github.com/users/tkurki/gists{/gist_id}","starred_url":"https://api.github.com/users/tkurki/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/tkurki/subscriptions","organizations_url":"https://api.github.com/users/tkurki/orgs","repos_url":"https://api.github.com/users/tkurki/repos","events_url":"https://api.github.com/users/tkurki/events{/privacy}","received_events_url":"https://api.github.com/users/tkurki/received_events","type":"User","site_admin":false},"created_at":"2018-03-02T15:42:20Z","updated_at":"2018-03-02T15:42:20Z","author_association":"OWNER","body":"Oh sorry, my mistake, I was misunderstanding what you were saying @bkp7.\r\n\r\nBut still some points: a vessel has a heading but an autopilot has a target heading. You can even set the target heading without engaging the autopilot. A fridge has a temperature but the fridge thermostat has a set temperature, and there may be just an icebox. Many of the sk paths are not subject to control.\r\n"}}
{"actor":{"display_login":"tkurki"}}