Conflicting API Calls

The following two APIs, as documented, conflict with each other with the result being that you can’t filter drivers that work with a specific device.

Retrieves the list of hub installed driver

Returns the list of drivers currently installed on the hub
Authorizations:
Bearer
path Parameters
hubDeviceId
required
	
string <^(?:([0-9a-fA-F]{32})|([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$>

The Hub's Device ID. This is sometimes referred to as the Hub UUID or HubId
query Parameters
deviceId	
string

optional filter to only return installed drivers that can be used by the passed in device

like this https://api.smartthings.com/v1/hubdevices/{hubDeviceId}/drivers/{deviceID}



Get Driver in use by Hub Device

Returns the specific driver revision information of the driver that is in use by a hub
Authorizations:
Bearer
path Parameters
hubDeviceId
required
	
string <^(?:([0-9a-fA-F]{32})|([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$>

The Hub's Device ID. This is sometimes referred to as the Hub UUID or HubId
driverId
required
	
string <uuid> 

like this https://api.smartthings.com/v1/hubdevices/{hubDeviceId}/drivers/{driverId}



If you use the deviceID after /drivers, you get the message:

{
  "error": {
    "code": "NotFoundError",
    "message": "Driver (77cc71e2-8094-4221-82b3-8fecacf24ae9) is not currently installed on hub 2ca01359-7f67-469e-9887-172e72b0423f",
    "details": []
  }
}

Hi, @h0ckeysk8er!

In this API endpoint, it says “deviceId” is a query parameter and it must be specified as such in the URL, for example:

https://api.smartthings.com/v1/hubdevices/hubDeviceId/drivers?deviceId=deviceId

I tested it and it only includes drivers for a Zigbee device I have installed, but if you have issues with it, please let me know.

About this one, it should show the info of the driver’s version installed on the Hub. In the docs, it doesn’t include deviceId as a parameter. What would be the issue in that case?

Hmm, I tried that earlier and got an error. I’ll try again and see what happens.

Thanks!

Ok, seems I was fat-fingering the case in deviceId and instead was doing deviceID. Ugh.

Interestingly, it filters properly for Z-Wave, Zigbee, and Matter devices. For LAN type devices, it returns all drivers on the hub. For VIPER type devices, it returns nothing. I see similar behavior on the Advanced Web App.

@nayelyz

Might I suggest that the API Reference documentation doesn’t really help users by not actually showing the path templates for any of the calls.

In this case you are literally only told it has the hubDeviceId in the path and the deviceId in the query string. They don’t tell you what the rest of the path is.

It is rather like giving you the arguments to a library function without ever telling you the name of the function.

The best they offer is the sort of example request and response thing which appears on the right of a desktop window, or way off the bottom of your screen on a mobile, and that really isn’t up to much.

1 Like

Hi, @orangebucket
I’ll share your comments with the engineering team to see if they can provide more examples in that page.

I don’t know exactly what the endpoint uses to filter the results but I’m guessing it uses the properties where the fingerprints are saved. As LAN devices don’t have fingerprints, it makes sense they don’t get filtered, but I’ll confirm with the engineering team.
The VIPER type is Cloud-Connected so, they don’t use drivers, their controllers are not listed there.

1 Like

Nayely,

It’s not a lack of examples that is the real problem. It is the lack of the URL path anywhere useful. If you start with a modest sized screen like a laptop and try and find the URL path for an API call you have to ignore the main body of the text, go to a rather low key side panel, and click on a tiny arrow. It’s not like you can do a lot without that information.

Try it on a mobile and its not even at the side, you have to scroll down a couple of pages before you even come to it.

As an aside, if anyone wonders how you know what fingerprints drivers have without actually looking in the package source, you can use:

https://api.smartthings.com/distchannels/{{channelId}}/drivers/{{driverId}}/meta

You, as in the user that generated the PAT you are using to access the API, have to be personally subscribed to the channel in order to see the metadata of the drivers inside it.

1 Like

Also available in the ST API Browser+

Oh yes, of course it is. I spend too long looking at the details and forget about the plan.

Ok, thank you for providing more details about what you meant.
I created a ticket about this and included the picture in your post for the team to look at.

2 Likes