Yet Another API Client

Developer Programs Support
1

I recently started exploring and testing the SmartThings API,

and I’ve made some great progress in fetching platform capabilities, rooms, devices, and controlling their status. However, I’ve encountered a challenge when it comes to querying each device capability and its syntax.

Currently, I’ve been manually matching capabilities using the capabilities reference documentation provided by SmartThings
(Production Capabilities | SmartThings Developers).
I extract the capability information from the response, like:

“capabilities”:[{“id”:“contactSensor”,“version”:1},{“id”:“temperatureMeasurement”,“version”:1},{“id”:“threeAxis”,“version”:1},{“id”:“accelerationSensor”,“version”:1},{“id”:“battery”,“version”:1},{“id”:“firmwareUpdate”,“version”:1},{“id”:“refresh”,“version”:1}]

Although this approach works, I believe there must be a more efficient way to accomplish this task. Is there a built-in method or API endpoint that can provide the syntax and details for each capability?

Additionally, I noticed the “presentation” call, which appears to break down every control and field required for feedback and control. However, I’ve noticed that not every device has a valid presentationID. Am I overlooking something obvious here?

Anybody interested in the development of a Microsoft Store C# app feel free to join the very informal Discord.

2

tagging @TAustin

3

Would be nice to read his opinion about it.
I believe he used the smartthing CLI for his project.
I think the presentations approach would sorta work (assuming I could be able to get every device and be cool to make 200 individual API calls)

4

@TAustin used the ST APIs for the API Browser+. These are the same APIs used by the ST CLI, but presented via a web interface vs a terminal command line. I’ll leave it to him to explain his methodology for retrieving the capabilities.

1 Like
5

excellent.
I just saw @TAustin STCLI in the APIB+ thread and I noticed that the ST CLI simplify a bit the presentation query.
smartthings devices:presentation [ID] ( ID the device id or number )

that use the device ID
while the STAPI seem to use the presentationId as QueryParameter
https://api.smartthings.com/v1/presentation?presentationId=xxxx

(that I can’t get on everydevice and only after I already parsed the device avaiable.
No idea if STCLI do a completely different STAPI calls or the server just return directly the right presentation to the to a STCLI request.

6

Here is the URL that is called when the Presentation button is pressed in the API Browser+:

https://api.smartthings.com/v1/presentation?presentationId=ST_XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&manufacturerName=XXXX&deviceId=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXXX&locationId=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
1 Like
7

You can retrieve a list of the the stock capabilities using https://api.smartthings.com/capabilities, or a list of the capabilities in one of your own namespaces using https://api.smartthings.com/capabilities/namespace/{{name}} but you have to use https://api.smartthings.com/capabilities/{{id}}/{{version}} to retrieve the details of each capability individually. I suspect there is very little demand for grabbing the content of all the stock capabilities in one go so that is probably the more efficient way of doing things from the point of view of SmartThings.

You are correct that not every device has a device presentation, though it is becoming increasingly rare not to see one in new integrations. The mobile apps can apply defaults.

The SmartThings CLI is an app that uses the Core SDK for accessing the API. If you put it into debug mode (set the environment variable SMARTTHINGS_DEBUG to something ‘truthy’) you can see API calls it is actually making.

3 Likes
8

yep, perfect. this works for devices that have no presentationId like this original ST switch:

“deviceId”: “ae381bba-3566-45fb-8536-0fe1bd998edc”,
“name”: “Z-Wave Switch”,
“label”: “4”,
“manufacturerName”: “SmartThings”,
“presentationId”: “SmartThings-smartthings-Z-Wave_Switch_Generic”,
“deviceManufacturerCode”: “0000-0000-0000”,
“locationId”: “2ca5a057-42db-4f3c-a18a-145c308634e8”,
“roomId”: “d72861ba-2ea2-4c2c-b054-4d03c8beeba9”,
“deviceTypeId”: “3416ebc5-0276-4884-a715-38672d8ede5d”,
“deviceTypeName”: “Z-Wave Switch Generic”,
“deviceNetworkType”: “ZWAVE”,
“components”: [… .
…
…

Even though the documentation assume that:
presentationId is required
the following (just the deviceID)
https://api.smartthings.com/v1/presentation?deviceId=ae381bba-3566-45fb-8536-0fe1bd998edc&locationId=2ca5a057-42db-4f3c-a18a-145c308634e8
works just fine.
Still “good form” would probably to keep using the (useless?) presentationId field

9

well, more than the generic list of all the capabilities I was thinking about a way to get the:presentations for each device in just one call.
I think I am a bit confuse when and where I want/should use capabilities or presentations, but now I have a lot more options to play with.

10

It does actually have a presentationId …

Presentations have evolved somewhat over the last five years and what you are seeing there dates from an earlier stage and is typical of a legacy device type handler for a stock device.

The manufacturerName acts as a namespace for presentations. The default namespace used by the API is SmartThingsCommunity.

11

Not at all. If you want to see the presentation in use by a device and you know the deviceId then the API will find the current presentation for you. If it is the presentationId that you know then you can use that directly, in combination with a manufacturerName if necessary.

1 Like
12

I get what you saying on a functional level; but the documentation specify that the presentationId is a “required” parameter.
I can’t imagine any scenario where I don’t have the deviceId so there must be some API design decision that lead to have 2 unique ID for the same equipment (?)

I fear that omitting a required parameter could just lead to incompabilities and future implementations.
I do like APIBrowser+ approach to just include every possible parameter everytime (the API seem pretty forgiven and it just ignore not valid parameters (beside deviceID)

for example this query (litteraly using those placeholder)

https://api.smartthings.com/v1/presentation?presentationId=ST_XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX&manufacturerName=XXXX&deviceId=e975f687-b554-42fb-bd58-396079d1b851&locationId=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

works just fine.

For my understanding a presentationID is unique and never shared across different deviceID or manufacturerName and the API should return an error if I would omit it.

13

Yes, that is odd as it also clearly states that if you use the deviceId you don’t need anything else. I suspect that originally the presentationId was required and the deviceId wasn’t an option, and then it was realised that having the API work out what was required was more efficient. Unfortunately the documentation doesn’t match reality.

A presentationId (also known as a vid) is unique within a namespace (the manufacturerName or mnmn). You need both, though the manufacturerName defaults to SmartThingsCommunity. The term manufacturerName is a little misleading really.

The presentationId keys both a ‘device config’ and a ‘device presentation’ in the API. The device presentation instructs the client apps how to present devices in the dashboard, device details and automation views based on their capabilities (the capabilities themselves having presentations for the same purpose). The device config is basically the user configurable bits of the device presentation. Within the SmartThingsCommunity namespace the presentationId is generated as a hash of the device config contents so the same device config created by multiple users results in the same identifier.

So multiple devices will have the same presentationId.

1 Like