Development with SmartThings API

Developer Programs Writing SmartApps
10

OK… so here’s a rough summary of what @balkcivil and I discussed. I’m hoping @Jim takes note and will be able to tell us what is planned in the short term documentation, with the rest going into the Community FAQs that @April is encouraging us to write …

This is meant to be a rough draft overview and may have various degrees of inaccuracy or consistency.

Terminology Is Important: Documentation Needs a Glossary?

  1. A SmartApp is not a mobile app (and certainly not THE SmartThings Mobile App). A SmartApp is often just a “rule” or “recipe” (if <open> then <turn on> <light>), where <x> are parameters – called Preferences in a SmartApp. A SmartApp, however, can be much more complex than basic rules, as developers write them with Groovy methods, access to some Java libraries, etc…; but they run in a sandbox as described in the Documentation. SmartApps are also used define Web Services end-points for External Applications.

  2. A Device Type is called SmartDevice Type in the Reference Documentation. I wish we had official acronyms to save typing… SDT?

  3. Device is a Class distinct from SmartDevice Type but has a lot of attributes and methods that map to the applied SmartDevice Type.

  4. I still don’t know the best definition of Thing, especially compared to Device. The terms seem sometimes interchangeable in the Documentation, so it would be good to clarify.

  5. SmartThings currently does not have any “widgets”. In tech terminology “widget” now commonly means a simple or highly functional user interface object that is placed on the desktop or other top level grouping on a phone, tablet, or computer. It is often a “shortcut” to the functionality of the full app installed on the same mobile or computer. The term “widget” is also similar to the term “control”, which is a user interface object within an panel in an app/application. – SmartThings calls these Tiles and they are available for developers to build a user-interface in a SmartDevice Type. http://docs.smartthings.com/en/latest/device-type-developers-guide/anatomy-of-a-device-type.html

  6. There are probably other ambiguous terms applicable to this Topic.

External Applications

  1. I define External Applications as applications other than SmartApps, the Mobile App, and the Developer Webpages & IDE (graph.api.smartthings.com). Some examples are *IFTTT, The Ubi,
    and **ActiON Dashboard".

  2. The Documentation about External Applications is at http://docs.smartthings.com/en/latest/smartapp-web-services-developers-guide/index.html ; but seems to be less complete than some 2013 drafts that I have seen. I am presuming that so much of the old drafts is deprecated that they are no longer useful; but I also think that current documentation does not fully document the REST-API and give enough examples.

    The “2013 drafts” that I mention are marked as copyright or internal, so I can’t share them directly.

  3. External Applications cannot be used to add or remove a Device from SmartThings (currently). The Mobile App must be used (though there are some force delete options available in the API).

  4. External Applications have access to a limited sub-set of REST-API endpoints without authorization, and a few more end-points with a general user login authorized id-key. Some examples, possibly deprecated, are in a community shared document on GitHub:
    https://github.com/tmaiaroto/smartthings-unofficial-docs/blob/master/Documentation.md

  5. External Applications have “full” (get and put) access to the REST-API endpoints applicable to each Device, only after obtaining the user’s authorization for each device via the OAUTH steps described in the official Developer’s Guide Documentation:
    http://docs.smartthings.com/en/latest/smartapp-web-services-developers-guide/index.html.

  6. This (and various discussions on SmartThings’s architecture and security model) implies and means that each time a user adds a new Device (which must be done via SmartThings Mobile App…), the authorization step needs to be redone for the External Application. So even a “full featured” External User Interface Application (like the ActiON Dashboard) cannot access new devices using the originally granted access token.

    I compared OAuth process to authorizing your Facebook account to be accessed by various services such as Rotten Tomatoes. There is some degree of granularity (Post on Feed with Public, Friends, Group of Friends, or “only me”; and so on). NB: in the Facebook analogy, if you add new Friends, Rotten Tomatoes does not need a new authorization (since Facebook’s granularity is at the Group of Friends level, but SmartThings is at the individual Device (Thing?) Level.

  7. This needs clarification and clearer wording:

    A special custom REST-API exposing SmartApp is required for some (most?, all?) External Applications, and there is an instance of these SmartApps for each External Application authorization. IFTTT and ActiON Dashboard are examples of this (the code is only shared for the latter). Authorizing The Ubi, though, doesn’t seem to need or create one of those SmartApp instances; so perhaps there are many default REST-API endpoints available and authorizable without a custom SmartApp (or more likely, I’m just not seeing The Ubi SmartApp … is it hidden or I’m lost?).

  8. The Open Sourced ActiON Dashboard is likely an excellent example of an External User Interface Application because it provides a full-featured User Interface using SmartThings Web Services (with a
    custom SmartApp to provide the REST-API endpoint mappings, etc.).

Questions and comments welcome!
…CP / Terry.