I’m trying to find the API to read the state of my devices and to send commands to them. Seems an essential part of the platform. Can someone shed some light on how to do these things with the current API? Ideally without creating any custom web services (which seem totally unnecessary for a core function like this).
Right now you’re limited to the functionality if the app(s) and the IDE (which shows status but you really can’t control anything). If I’m missing something, someone from ST chime in.
@rickbullotta – There’s a supported-but-not-yet-fully-documented method of exposing your own API endpoints to subscribe to events and control devices from third-party web services. The initial documentation is available here:
There also an example SmartApp that exposes web services is available in the IDE under Browse SmartApps -> Sample Web Services. As you start to think about how you want your external web service to interact with your devices, send an email to build@smartthings.com and we’ll help you through the undocumented sections.
The reasoning behind this architecture is that, like SmartApps that run entirely in the SmartThings Cloud, external web services should only have access to the explicit security context that is set up by the user.
The reasoning behind this architecture is that, like SmartApps that run entirely in the SmartThings Cloud, external web services should only have access to the explicit security context that is set up by the user.
I am not sure I understand the motivation and limitations of this; but my experience with open API’s to proprietary web-services is limited.
I can’t understand why “full” (or “nearly-full”) front-end API access can’t be granted, because other companies seem to be able to do this in other contexts:
Examples (some of which may make no sense in this context, but I’m grasping…) – as done through access tokens:
Login/authentication services from Facebook, Google, etc.
API's to access GDrive, Dropbox.
Use of GTalk (google communication layer), for VPN's and integration into other chat clients and more.
Others: ? ... maybe the community here has many other applicable examples?
I have two personal motivations that are driving my concern on this topic:
The current GUI has significant design elements that I disagree with. I'm sure some will be improved/evolved by SmartThings (e.g,. landscape orientation, web GUI, ability to put a Thing into multiple Groups like icon shortcuts (soft-links) in Windows, SmartApps having the ability to call other SmartApps, calling a SmartApp directly from a tile (not just subscribing to an event), ...); but a lot of this official current "look-and-feel" will likely persist, I presume.
There are many competing (and complementary) home automation / connected "thing" ecosystems coming online soon (various Kickstarters and new products from established vendors). Many of these are providing their OWN clouds and front-end mobile apps; different APIs, rule languages, etc..
As a result of 1 & 2: I would like to know that we could have the ability if desired to code our own UI's (and expanded APIs) such that we can maximize the ability to quickly innovate and integrate: I'll bet there are a few dozen members of the "Developer Community" who could program a workable web based front-end UI to SmartThings in just a few weeks, if given full access to the API. This GUI might not look anything like the SmartThings mobile UI... but that is not necessary a bad thing. It would not take away the ability for ST to provide their own official web UI; let the customer's choose which to use (or buy, or integrate with competitor's, ...).
But, also, again, again … I perhaps am just not clearly understanding specifically WHAT is or is planned to be exposed and documented in the official public API’s, and which extra stuff that official “partners” will get (and how to become a partner!?!), and what stuff will never be exposed.
Well… After writing all of the above, I went back and skimmed this document; and it is helping me understand the environment a bit more and I am a little bit more optimistic.
EXCEPT: Well… the document has a lot of sections with no information in them yet.
@tgauchat - These are great questions, and I’ll answer them to the best of my ability.
First, the SmartApp Web Services methodology does in fact authenticate users through access tokens in the same way as the other web services that you’re mentioning - via OAuth. We use an OAuth2 flow, as most web services are doing these days. The authentication bit isn’t the part that we’re concerned about when it comes to the security context - it’s about what the client can do once it’s authenticated to the service. This is the crux of a pretty hotly debated discussion within the company - using the core API, once a client is granted access it can do anything our mobile clients can do. It can add and remove devices. It can add and remove SmartApps. It can control devices such as lights, garage doors, and door locks. This is where SmartThings starts to differ from many of the other services that you describe, and this is why a lot of extra care as been taken to ensure that the user has a very explicit role in setting up their security context. From a SmartApp perspective, SmartApps cannot enumerate a user’s devices. This means that a SmartApp that claims to read the status of a temperature sensor can’t maliciously unlock the front door because it has no knowledge of any devices in the user’s physical graph beyond the temperature sensor device that the user told it about.
To get to your specific points:
I totally understand that you have specific UI/UX issues with the current incarnation of the mobile client. You're not the only one - so do we. We're working hard on evolving the experience, and within a few months you probably won't recognize it. And we're working to add some of the flexibility around SmartApps that you're describing, and more.
Yes. We love all of the open platforms that are being developed in the marketplace, from Kickstarter, to IndieGoGo, to other commercial interests. We are committed to keeping our platform open so that integration with these other ecosystems is possible. We're working on this from four main angles:
Cloud-Connected Devices: One of the major initiatives that is currently underway includes allowing cloud-connected or "virtual" device types in the SmartThings platform to authenticate with remote cloud services via OAuth2. This includes things like the Ecobee WiFi Thermostat, a WiThings WiFi scale, or potentially even something like the Nike+ Fuelband. We'll develop a number of integrations directly (we're working on some cool ones) and we'll open up those APIs so that members of the SmartThings developer community can create their own. Another example of this, though without the OAuth2 authentication flow, is @dianoga's SmartNest (http://build.smartthings.com/projects/smartnest) project that connects directly to the Nest web service, but implements the SmartThings Thermostat capability, so SmartApps don't know or care whether they're talking to a Nest, a Radio Thermostat Z-Wave Thermostat, or a Honeywell Z-Wave Thermostat.
Hub-Connected Devices: There are a number of Kickstarter projects out there, amongst others, that have indicated interest or commitment to compatibility with SmartThings. Most of these devices (PlantLink, FilterWatch, Linkbot, etc) include a Zigbee HA radio, and we'll provide the necessary support to integrate it into the platform.
LAN-Connected Devices: An upcoming release of the firmware will allow the SmartThings Hub to act as a proxy device to the users local LAN. Initially, we'll support devices that can be discovered by and communicated with via the UPnP suite of protocols. We'll also be able to discover devices that advertise themselves via SSDP (part of the UPnP suite) and are communicated with via HTTP.
SmartApp Web Services: This is what is described in the unfinished document that you referred to earlier. This is a method by which SmartApp developers can expose their own web services that can both accept commands from a remote web service, or send event data from a user's devices off to a remote web service in response to a callback subscription. This is where the user must explicitly set the security context so that the web services exposed by the SmartApp can only see the data from, and accept commands for the devices that the user allows at install-time. No pretending that you're going to turn on a light switch, but instead open the garage door.
Using the Cloud-Connected Devices APIs and the SmartApp Web Services mechanism, you can go a pretty long way to doing what you're describing. You can't, however, write your own client that does things like put the hub in pairing mode, deletes devices, or has unilateral read/write access to all devices in a given users' physical graph. This gets to another hotly debated discussion within the company - if a user WANTS to trust a developer, should they be allowed to? What if I'm a developer, and I want to be able to do these things only in my own environment? I think there's probably some happy medium here - a sliding scale certification program like what Apple introduced with Gatekeeper that requires the user to explicitly allow applications developed by non-certified developers, or a developer token that gives developers access to the core API, but only for their own environments - and these are certainly up for discussion and not off the table. But they're also not going to make their way to the front of the backlog right away - there are a lot of things that our small engineering team has left to tackle to get to where we really want to be for a broad release of the platform.
I know none of these are perfect answers, but it’s exchanges like this that help move the conversation forward and help us to understand what our users and developers want, so please keep the questions coming.
As for the unfinished documentation - we know it’s a problem, and we’re working on it as quickly as we can. Which, to be honest, isn’t very quickly given the current resource demands on our team. I’d suggest that you start working your way through what is there, and send an email to build@smartthings.com when you get to the last 4 steps (the empty sections in the document) and we’ll help you through it via email - and those email exchanges will probably form the basis of the rest of the documentation.
Thanks,
-d
2 Likes
tgauchat
(ActionTiles.com co-founder Terry @ActionTiles; GitHub: @cosmicpuppy)
10
@dlieberman: Thank-you so much for that detailed answer. I appreciate the time and effort that took, and it is quite reassuring!
You have actually “fully” answered quite a few of my questions, even if some responses are just in the form of your future plans.
I will read and review this again in more detail, as well as the other available documentation and references. There is a lot to learn and think about.
I look forward to some specific discussions with you in email, and the continuing community sharing as well. I interact here a lot in order to see how my priorities and concerns match up with others.
Sincerely,
…CP.
tgauchat
(ActionTiles.com co-founder Terry @ActionTiles; GitHub: @cosmicpuppy)
11
@dlieberman: BTW: I think your responses (or some variation…) would be informative to a lot of Developers, and perhaps could be a good Topic for a Blog Post or other way of increasing visibility.
I think I should have full API access to my hub from within my own network.
Being forced to use the cloud brings in a whole mess of auth complexity and limitations.
