Undocumented API operation

sbarrett · September 28, 2021, 4:07pm

Hi,
In response to a query I was pointed at an API operation that is exactly what I need to accomplish my task. It gives me historic event data of a device. However because the operation is undocumented I have concerns about using it.
Operation:

https://api.smartthings.com/v1/history/devices?locationId={{LocationID}}&deviceId={{deviceID}}

Questions:

Is there a plan to include this operation in the documentation in future?
How likely is this operation to be removed from the API, deprecated or altered in a way to make my integration malfunction?

I asked Samsung support who told me to ask SmartThings support, who in turn directed me to the community.

Is there someone who can help with this?
Seamus

orangebucket · September 28, 2021, 5:07pm

Fair question.

I derived the endpoint information from the official SDK for JavaScript/TypeScript, which wraps the API. So it is mixed messages really.

erickv · September 28, 2021, 5:33pm

@sbarrett I couldn’t say for sure if this is going to be documented or deprecated, but let me share this with our engineers and as soon as I have a resolution, I’ll ping you back!

Jason_B · September 28, 2021, 6:59pm

@orangebucket - do you mind sharing the link to the source file you found?

Jason_B · September 28, 2021, 7:25pm

Also, is there any REST API documentation available online anymore? I keep seeing references to https://smartthings.developer.samsung.com/develop/api-ref/st-api.html all over these boards but on the new site, is there any place to find this? Basic stuff, like get the status of a light switch is what I’m looking for. Thanks!

orangebucket · September 28, 2021, 7:38pm

github.com

SmartThingsCommunity/smartthings-core-sdk/blob/master/src/endpoint/history.ts

import {Endpoint} from '../endpoint'
import {EndpointClient, EndpointClientConfig, HttpClientParams} from '../endpoint-client'
import {PaginatedList} from '../pagination'


export interface DeviceActivity {
	/** Device ID */
	deviceId: string

	/** Device nick name */
	deviceName: string

	/** Location ID */
	locationId: string

	/** Location name */
	locationName: string

	/** The IS0-8601 date time strings in UTC of the activity */
	time: string

This file has been truncated. show original

That was enough to allow me to figure out the structure.

Only really API | SmartThings Developers which is the same as it always was but with different styling.

GSzabados · September 29, 2021, 4:46am

@erickv, maybe the issue should be raised at management level. As the documentation has not been updated for many things for a while. (Giving a new skin to it doesn’t change the fact that many things are missing…)

Has any of the thermostat vids has been documented since 2019?

Are the pre-defined vids documented at all?

Why is the vid selector a suspended project on Glitch as well?

sbarrett · September 29, 2021, 8:07am

Thanks for the responses. @erickv I’d be very interested to know what the engineers and/or management think.

erickv · September 29, 2021, 2:05pm

@sbarrett @GSzabados

I’ve shared your inquiries with our team, not only your concerns about the future of this API and if we can still rely on it, but also the feature request to document the History API.

As soon as I have an update, I’ll let you know.

GSzabados · September 29, 2021, 2:24pm

@erickv, don’t waste your time on my inquire. I have asked the same question about the thermostat vids back in February of 2020 through the official support email and the build email as well. Fabiola Vega took care of it. Since then no change on the documentation…

erickv · September 30, 2021, 12:48pm

Hey, @sbarrett

I’ve been discussing your concerns with some of our engineers in charge of this API, but unfortunately, there’s no plan to make the spec public.

However, to get some track with this inquiry, I’ve documented a Feature Request that will be reviewed as soon as possible, and for now, I recommend you to keep track of the following release notes pages:

Undocumented API operation

Customers

Developers

Download the SmartThings App