Align REST and WebSockets APIs for actions and events - closes #33

[benfrancis]

This is an attempt to better align the payloads of the REST & WebSocket APIs for actions and events, to fix #33. Follows on from the discussion in https://github.com/mozilla-iot/wot/pull/45

This feels cleaner and by using object keys it gets rid of the use of the "name" property term which is used elsewhere for human-readable strings.

It does make the list of /actions and list of /events a bit more clunky but it is at least more consistent.

[benfrancis]

One snag might be when we add more complex examples of actions with arguments (and possibly return data) https://github.com/mozilla-iot/wot/issues/17 and events with more complex payloads. Depending on how we do that there could be name collisions between argument names/event payload items and the other properties in an action and event payload and we might want to prefix properties like timeRequested, status and href with an underscore or something. But it depends what solution we come up with because there are various proposals at the W3C.

[hobinjk]

I'm not sure I like the /things/pi/actions/action-key/action-id (e.g. /things/pi/reboot/12345) format, it seems a bit redundant to specify both. What is your motivation?

[benfrancis]

I'm not sure I like the /things/pi/actions/action-key/action-id (e.g. /things/pi/reboot/12345) format, it seems a bit redundant to specify both. What is your motivation?

See #66

It allows us to have both a queue per action and a queue of all actions (for convenience). But we should discuss that in #66. Note that the URL structure is not part of the spec though, developers can theoretically choose any URL structure they like, this is just an example.

[hobinjk]

Oh okay, cool! That definitely works. Could the spec explain whether a POST to /things/pi/actions/reboot

{
  "time": "now"
}

is equivalent to POST /things/pi/actions

{
  "reboot": {
    "time": "now"
  }
}

[benfrancis]

Hmm, interesting question. You can certainly argue that in the former case the key "reboot" is redundant, but I would actually suggest that they should both be the same:

{
  "reboot": {
    "time": "now"
  }
}

When you get an action request it's of the form:

{
  "reboot": {
    "time": "now",
    "href": "/things/pi/actions/reboot/123e4567-e89b-12d3-a456-426655"
    "status": "pending"
  }
}

and when you get a list of action requests it's of the form:

[
  {
    "reboot": {
      "time": "now",
      "href": "/things/pi/actions/123e4567-e89b-12d3-a456-426655",
      "timeRequested": "2017-01-25T15:01:35+00:00",
      "status": "pending"
    }
  },
  {
    "reboot": {
      "time": "now",
      "href": "/things/pi/actions/153e3567-e89b-12a3-a456-426351",
      "timeRequested": "2017-01-24T11:02:45+00:00",
      "timeCompleted": "2017-01-24T11:02:46+00:00",
      "status": "completed"
    }
  }
]

So this way it's consistent across all the requests. It also keeps it more consistent with the requestAction WebSocket message.

BTW, in the above examples you can see where the name collisions might happen once we specify action arguments (#17).