No full descriptions of responses to WebSocket calls

[Neurogami]

There is an example of using the Websock API but it does not explain what each request can expect in the callback. The REST API has some of this information but the API is different in some places (e.g. WS: use "register" to register a device; REST: post to "/devices"). Through experiments I found that a WS call to "register" returns a token, eventCode number, device string, channel, a few other things.

Perhaps all this can be derived by digging through every example but having a single place listing calls and the possible responses would be helpful.

[octoblu]

Websocket API commands include: status, register, unregister, update, whoami, devices, subscribe, unsubscribe, authenticate, and message. The websocket API mimics the skynet.js examples. Here are a few examples:

  // Sample SkyNet API calls:
  socket.emit('status', function(data){
    console.log('status received');
    console.log(data);
  });
  // Subscribe and unsubscribe to a device's messages and events
  socket.emit('subscribe', {
    "uuid": "0d3a53a0-2a0b-11e3-b09c-ff4de847b2cc",
    "token": "qirqglm6yb1vpldixflopnux4phtcsor"
  }, function (data) {
    console.log(data);
  });

  socket.emit('unsubscribe', {"uuid": "0d3a53a0-2a0b-11e3-b09c-ff4de847b2cc"}, function (data) {
    console.log(data);
  });

  // Send and receive messages
  socket.emit('message', {
    "devices": "*",
    "payload": {
    "skynet":"online"
  }}, function(data){
    console.log(data);
  });
  socket.on('message', function(message){
    console.log('message received', message);
  });

  // Get the status of the SkyNet network
  socket.emit('status', function(data){
    console.log('status received');
    console.log(data);
  });

  // Register device
  socket.emit('register', {
    "type":"drone"
  }, function (data) {
    console.log(data);
  });

  // Update device
  socket.emit('update', {
    "uuid": "0d3a53a0-2a0b-11e3-b09c-ff4de847b2cc",
    "token": "qirqglm6yb1vpldixflopnux4phtcsor",
    "armed":true
  }, function (data) {
    console.log(data);
  });

  // WhoAmI?
  socket.emit('whoami', {"uuid":"0d3a53a0-2a0b-11e3-b09c-ff4de847b2cc"}, function (data) {
    console.log(data);
  });

  // Receive last 10 device events
  socket.emit('events', {
    "uuid": "0d3a53a0-2a0b-11e3-b09c-ff4de847b2cc",
    "token": "qirqglm6yb1vpldixflopnux4phtcsor"
  }, function (data) {
    console.log(data);
  });

[Neurogami]

None of those examples show what is returned. All it shows is "console.log(data)". What is data? Is it ever used? Does it vary based on what parameters are sent?

Based on these examples a Websocket client can ignore what comes back and never needs to use it.

I look at these examples and they make little sense because they do not demonstrate any real-word use. What's returned by "events"? Why would it be called only to do console.log?

The examples are too sparse and do not make clear what return data are provided. Makes it hard to write client code in Lua, Java, etc. since there are few explicit details documenting behavior.

[octoblu]

The response results for the websocket API should be the same as the REST API. See http://skynet.im/#api

[Neurogami]

"The response results for the websocket API should be the same as the REST API." They are not. That's part of the problem. For example, there is no REST item called "register" . Instead, there's a POST to /devices. This lack of a direct correspondence between the tow APIs suggest there are gong to be discrepancies. What are they?

The docs fr posting to /devices' there say, "SkyNet returns a UUID device id and security token. "

When called via the Websocket I get back much more:

{"timestamp":1395357227025,
             "_id":"532b762ba8b3766426000009",
             "token":"1gk7jckoswp6tj4iisoc4vddy22o6r",
             "eventCode":400,
             "device":"P5",
             "uuid":"4a055811-b085-11e3-8217-79d204ef5ee7",
             "channel":"main",
             "ipAddress":"",
             "online":false}

What do these mean? If my code doesn't do what I expect, would these values (or that fact that some are missing) help explain that?

Since these values get returned there's a presumption that they must mean something and have some practical use. But what? Where is that explained?

The docs and examples seem to be written from the POV of someone who wrote the code and already knows how everything is supposed to work and what to look for if something does not.

There needs to be something more robust to fully describe the protocol. I.e. Here are all the possible arguments you can send, and why you might include or omit them. Here are all the possible values you might get back, what each means and what they could, should, or must be used for.

[octoblu]

I added a new example section to the site with REST, NodeJS, and Skynet.JS examples - http://skynet.im/#examples

I also added responses to the websocket api docs - http://skynet.im/#websockets