The document outlines the design of a Thing API, using Philips Hue as an example for controlling multiple lights through a hub. It emphasizes the importance of defining unique identifiers for devices, understanding input (istate) and output (ostate) states, and improving API structure with semantic vocabulary. The document also discusses potential improvements in API usability and the differentiation between actual states and desired states.

1. What should a Thing
API look like?

2. David Janes
@dpjanes
davidjanes@iotdb.org
http://iotdb.org/social/imadeit/
April 2015

3. e.g. Philips Hue
• Multiple Lights
• Controlled through Hub

4. N.B.
• We’re ignoring:
• pairing
• authentication
• security

5. N.B. also
• The Hue API is pretty close to this now!
• But there’s lots of bad APIs out there

6. API Entry
GET /api
{
"things": "/api/things"
}

7. Things
GET /api/lights
{
"1": "/api/things/1",
"2": "/api/things/2",
"3": "/api/things/3"
}

8. Thing 1
GET /api/lights/1
{
"state": "/api/things/1/state",
"meta": "/api/things/1/meta"
}

9. Thing 1 State
GET /api/lights/1/state
{
"on": true,
"color": "#FF0000",
(other stuff)
}

10. Thing 1 State
PATCH /api/lights/1/state
{
"color": "#FF9999"
}

11. Thing 1 Meta
GET /api/things/1/meta
{
"uuid": "0000-…-000",
"name": "My Living Room"
}

12. Thing 1 Meta
PUT /api/things/1/meta
{
"name": "My Basement Den"
}

13. Improvements

14. @context
explain terms
GET /api/things/1/state
{
"@context": <some url>,
"on": true,
"color": "#FF0000",
(other stuff)
}

15. @type
what is this?
GET /api/things/1/state
{
"@type": [ "Thing", "Light" ],
"on": true,
"color": "#FF0000",
(other stuff)
}

16. @id
where am I
GET /api/things/1/state
{
"@id": "/api/things/1/state",
"on": true,
"color": "#FF0000",
(other stuff)
}

17. IOTDB
• Semantic vocabulary
• defines what (e.g.)
• “on” means
• “color” means

18. Use real IDs
• Instead of 1, 2, 3…
• Use unique IDs for each device

19. istate & ostate

20. Two States!
• input state “istate” - what my values are
• output state “ostate” - what I want them to
be
• not always - frequently not - the same

21. Thing 1 (revisited)
GET /api/lights/1
{
"istate": "/api/things/1/istate",
"ostate": "/api/things/1/ostate",
"meta": "/api/things/1/meta"
}

22. istate
• The “input” (toward me) state
• The actual state of the Thing

23. ostate
• The “output” state
• What we want the state to become

24. why two states?
• developers are used to things working or
failing
• when you tell Things to do things, this
becomes more indeterminate

25. Get in touch!
David Janes
@dpjanes
davidjanes@iotdb.org
http://iotdb.org/social/imadeit/