API limits and Webhooks

Developer Programs Support
1

Hi,
I made a smartthings logged oauth app that I am using to manage my smart home via smartthings. It’s working great but I have 3 questions:

  1. What are the API limits? Now I have only 2 devices added to my account, but what if I had 200? Or 2000. I am not sure if this applies to me with oauth /docs/getting-started/rate-limits

  2. Is it possible to set webhooks? The devices I use are thermostats (Meross), and I can see on smartthings temperature report updates every 20 minutes or so or on major changes. For now the only way of getting the new temperature is to make an API call for that specific device, getting the latest possible temperature. Would it be possible to set up webhooks for smartthings to report to my server whenever a change happes? New temperature, device offline, etc…
    This way I would save a lot on computing power and API calls, while at the same time having a super responsive and always updated app

  3. I use a double API call to update my database. 1st I use api. smartthings.com/v1/devices to get my device list and api. smartthings.com/v1/devices/{deviceId}/status to get the specific devices info (as in point 2, temperature, on off status, etc…)
    If I had 50 devices that would mean 51 API calls to update all of them. Is there a way to have a single API call that merges both data and gets device specific infos in the more generic API call?

Thanks!

1 Like
2

Yes, you can set up Subscriptions for a Webhook SmartApp. Your app will receive a POST when the subscribed event(s) occurs.

2 Likes
3

I am assuming you have used the OAuth flow to get a renewable access token instead of a PAT. This is part of the process of creating an OAuth-In app, also referred to as API Access in the example apps, and known as API_ONLY in the API.

1)

I rather assumed they would get the same as other installed apps but as you have noticed OAuth-In apps aren’t mentioned.

2)

The ‘Target URL’ you are asked for when creating an app via the CLI is the Webhook. You will note lots of documentation about lifecycles for Webhook SmartApps. OAuth-In apps have something similar except with messageType instead of lifecycle in the received POSTs. In particular they require the CONFIRMATION cycle to be handled and they receive EVENT messages. They do not receive CONFIGURATION, INSTALL or UPDATE messages and the messages are a little leaner but identical where it matters. EVENT messages don’t come with a five minute token, you use your saved access token.

3)

Sure. Use the Accept Header method of selecting the API version and use 20170916 as the version number instead of 1. You can then list all your devices using:

https://api.smartthings.com/devices?includeHealth=true&includeStatus=true

You will get the health and capability statuses included. Only use this version number for the devices endpoint. The output may be paged as described in the API reference if you have a lot of devices.

This version number thing happens automatically if you are using the JavaScript SDKs.

If you are making a lot of API calls in quick succession try to reuse existing connections if you can as there is a lot of overhead in setting up secure connections.

1 Like
4

Hi, @Francesco_Rubino
Just to add to what others have said:

There’s a limit of 300 devices per location. The rate limits should apply here as well.

When you get an Access Token through an OAuth integration, you also get an installedAppId which you can use to configure the subscriptions mentioned by the others.
But, remember you must configure the Target URL since that’s where you’ll receive these events only. The confirmation (verification step) is similar to the one from a SmartApp where you get the confirmation URL and must make a GET request.

1 Like
5

Thanks for the answer!

  1. indeed, and the API does not return anything

  2. I’ll check it out

  3. I tried both methods in the link but it does not look like it’s working
    -https://api.smartthings.com/v20170916/devices?includeHealth=true&includeStatus=true
    This one simply fails

-Accept: application/vnd.smartthings+json;v=1
This one returns the devices list but without the status I need

Are you currently using it? maybe i get something wrong?

6

But can one account have multiple locations, hence that limit can be increased?
To which API limits are you referring to? The guide says that it should give me my current API limit, but all I see is this:

{
id:"qwe-qwe123"
"status":"accepted"
}

Thanks for the webhook comments

7

I meant to use an Accept header of

Accept: application/vnd.smartthings+json;v=20170916

… and just begin the URL path with /devices. Not only do I use it all the time, it is also used in the ‘Core SDK’ and so by other SDKs built on top of that. The CLI uses it. It enables the use of includeHealth and includeStatus in the query string.

You only really want to use it when accessing /devices though.

8

The limit would still be 300 per location and each user has a limit of 10 locations.
In the response from the API you should see three headers (as mentioned here):

  • X-RateLimit-Limit: Maximum requests allowed within the rate limit window.
  • X-RateLimit-Remaining: Remaining requests available within the window.
  • X-RateLimit-Reset: Time in seconds until the current window expires.

So, you can base on that info about the limits.