First off, thanks for the websockets API. I've been developing an app against it, and it gets the job done (for the most part). That said, here's some unsorted feedback:
SecurityI'll echo what has been mentioned a few times already in this thread:
secure transport (wss://) is absolutely imperative. This is a worthwhile read:
https://devcenter.heroku.com/articles/websocket-security. Also, including the username/pass in the URI is particularly bad since secure transport won't conceal this from passive network sniffing. It's the security equivalent of walking around with your most important password written on your forehead.
Consistency in naming conventionsCase inconsistencies:
- Command names — "createrule" vs "ClientList"
- Attributes in the return object — "CommandType" vs "commandtype", "DeviceID" vs "deviceid", "Name" vs. "name", etc.
Attribute name inconsistencies:
- In the response — "devid" vs "deviceid"
- In the request — "mii" vs "MobileInternalIndex" and "cmd" vs "CommandType"
I've started including the 32-char random key as both both "mii" and "MobileInternalIndex" attributes, which the protocol seems just fine with. However, if you supply both "cmd" and "CommandType" (even if they're the same), it works for some commands ("devicelist" for instance), while other commands (such as "DynamicSceneList") will return this: { "mii":"<random key>", "commandtype":"unknown" }
Incomplete documentationThis is somewhat expected seeing as the API is all shiny and new. It's cropped up mostly when I'm looking for a list of acceptable values for a particular parameter. For instance, I was trying to activate a specific rule, so I sent the following:
{
"mii":"<random key>",
"cmd":"validaterule",
"ruleid":"<ruleid>",
"value":"true"
}
Well, this didn't work. Turns out, the
value attribute was expecting either a "1" or a "0" — even though the response data shows "true" or "false" (ex: "data":{"value":"true","ruleid":"<ruleid>").
Structural weirdness (possibly typos?)Here's the sample request for
ActivateScene:
{
"CommandType":"ActivateScene",
"MobileInternalIndex":"324",
"Scenes":{
"ID":"11"
}
}
Should the "Scenes" attribute be an array?
Thanks for reading! Oh, and who should I talk to about wiki edit rights for the documentation?