Unclear that API can take take device name instead of device ID

Cloud
1

The API docs lead one to believe that you must call the API with the core ID when calling any Core-related functions. But the command line interface docs give some examples that made me wonder if this was actually true. Testing with raw curl commands, I can see that it’s not – you can indeed use the device’s name instead of the ID

curl "https://api.spark.io/v1/devices/MY-DEVICE-NAME?access_token=MY-ACCESS-TOKEN"
{
  "id": "55ff6d066678505510411367",
  "name": "MY-DEVICE-NAME",
  "connected": true,
  "variables": {},
  "functions": [
    "updateLamp",
    "setGrove",
    "getGrove"
  ],
  "cc3000_patch_version": "1.29",
  "last_heard": "2015-05-01T20:39:54.051Z"
}

I was wondering though, when using the Spark Javascript library, why calling getDevice with a name instead of the ID I was getting a null return for the device

// After logging in
spark.getDevice("MY-DEVICE-NAME")
  .then(console.log.bind(console,'DEVICE'))
  .catch(console.log.bind(console, 'ERROR'));
> "DEVICE null"

Digging through the source to find out why, it comes down to this check

if (data && (data.id == deviceId)) {
  device = new Device(data, this);
}

This obviously isn’t true if deviceId wasn’t an id to begin with but rather a name

It would be great to update the documentation to reflect the fact that you can use the name instead of the ID (cause it’s a feature, not a bug!), and then remove this restriction from the Javascript library. I think it would be sufficient to just check for the presence of data.id

1 Like
2

Just a random question that pops up, haven’t tried it: what happens if two devices have the same name? I can imagine not having documented this to prevent confusion. Let’s ask @Dave how exactly this is supposed to work.

2 Likes
3

@Moors7 i believe your account/access_token will first be checked and your list of devices will be matched though others might have the same name :wink:

4

But then what? Let’s say I own two devices called “test” which both have functions called “testfunction”. What happens if I try to call that using the device name? I think that’s why it’s chosen to document the deviceID, so you have a unique identifier.
I’ll try to test it in a bit to see what happens.

1 Like
5

The system won’t let you name two of your own devices the same thing. The response from the API looks like

{
  "ok": false,
  "errors": [
    "Name already in use"
  ]
}

Also, documentation isn’t a subjective thing. You shouldn’t pick and choose what you document about a system. If something exists and functions in a specific way then the documentation should reflect that. This is especially true if examples rely on the undocumented behavior.

2 Likes
6

Just opened a pull request for sparkjs, changing the check for data.id === deviceId to just data.id

7

Hi @louis_

I think that using names instead of numbers was always part of the “original design” of the web API, but I can tell you for sure that it was not working around a year ago when I tried it. Between then and now, the Spark Cloud code got fixed/updated but the doc and SparkJS have the old state in them. It seems very likely to me that it wasn’t doc’ed at the time because it didn’t work then and now that it is fixed, the doc and supporting players like SparkJS need to updated. That’s all.

8

Apparently the web IDE doesn’t care as much as whatever you chose to try it with :wink:

[
  {
    "id": "53ff6d055555535140381687",
    "name": "eventss",
    "last_app": null,
    "last_ip_address": "212.120.92.238",
    "last_heard": "2015-05-04T18:57:32.772Z",
    "connected": true
  },
  {
    "id": "53ff70055555535148151387",
    "name": "eventss",
    "last_app": null,
    "last_ip_address": "212.120.92.238",
    "last_heard": "2015-05-04T19:08:57.917Z",
    "connected": true
  },
]

On a side note, don’t call your device “events”, it will conflict with the SSE adress. Been there, done that, was confused… :sweat_smile:

3 Likes
9

I’ll log a bug for that, the build IDE shouldn’t allow that! :smile:

Thanks,
David

1 Like
10

Very interesting! I got my result just using curl on the REST API. Does the IDE not use the same REST API? What were your steps for getting that result @Moors7?

11

Seeing as it’s a bug, you might not want to try to replicate it. I’m not entirely sure what API the IDE uses, but this slipped through the cracks I guess. That was why I was initially against using the name as an identifier.