Modeling APIs for IoT
The Internet of Things allows devices to communicate via APIs. But device APIs are different from most other mainstream APIs, because the device has state, and the available actions on a device depend on its state.
Mainstream API description languages generally don't have the full set of abstractions required for modeling these APIs. In this session, we explored the key abstractions and semantics of device-centric APIs, and translated these into a layer of extensions on top of a prototypical API modeling language. (Both the base modeling language and the extension layer were specified at a high level of abstraction.)
#Base Metamodel for API Modeling
A prototypical metamodel, or abstract syntax, for an API modeling language looks something like this:
Though Swagger, RAML, API Blueprint and WADL vary in their terminology and structure, they all have these basic concepts and roughly the same quasi-hierarchical relationships shown here.
Next, we looked at Zetta, a framework developed by the IoT team at Apigee. Zetta uses SIREN as the media type for its messages. (Special thanks to Adam Magaluk for explaining to all of us on how his works.)
We drew a state diagram for a thermostat, and asked how we would model an API for this using Zetta.
Zetta describes the Thermostat something like this:
- The device is represented as a resource, with the relative URI /device/1234
- The device has some property values associated with it.
- It has a specially designated property called “State” that indicates an overall state of the device.
- States are defined implicitly as part of “allowed action” rules. Allowed actions specify the actions that can be taken when the resource is in a given state. In this example, when the thermostat is in the ‘off’ state, available actions include ‘set to cool’ and ‘set to heat’.
- Zetta does not model composite/concurrent state, so the temperature parallel state shown in the state diagram would just be represented as a property.
- Zetta defines actions, and returns affordance hyperlinks to invoke these actions. Actions do not specify a target state that the resource is expected to enter on successful invocation of the action. Target state is shown in the above outline as a proposed extension to the Zetta model. Zetta also includes a link to monitor the device. This is a websocket like, providing a stream of notifications.
- Zetta allows a device resource to inherit from a “meta”, which represents a type of device, specifying some of the properties, states, allow actions and Links that are expected on a device of that type.
Contemplating how we might extend Zetta’s model, we talked about Device Groups as another possible type of resource. A device group could aggregate other resources and provide actions (e.g. “vacation mode”) that translate into multiple actions on the device resources within the group. Membership of a device in a device group would probably not be mutually exclusive, but it might be useful to enforce this in some cases.
It will often be the case that individual, small-scale devices expose their interfaces through intermediaries. This suggests that the reporting of device state and acknowledgement of action requests can be qualified. Since we’re not talking directly to the device, we may not be 100% assured of its state. This could be accommodated globally in the protocol, or on a case-by-case basis, adding more detailed and specific values tto response messages. For example, a response message could distinguish between “action requested,” which just acknowledges that an action request has been forwarded to a device; and “thermostat set to cool”, which says definitively that the action is known to have succeeded.
#Extending the Metamodel
We distilled this into an extension of our prototypical API description metamodel:
- DeviceResource is a subtype of Resource.
- A DeviceResource can have a DeviceType, analogous to the “meta” resource defined in Zetta.
- The DeviceResource (or its DeviceType) can specify States, Actions, and Allowed Actions. Allowed actions associate a state with actions allowed while the device is in that state.
- Actions are just like Methods (possibly inheriting from Method), adding only an optional target state (“new state”) that the device is expected to be in after receiving a given response.
- Just as a standard hypermedia response can have links, so can a response message on a DeviceResource Action .
- One of these may be designated with a Link Relation indicating that it is the monitoring link for the device. Since the monitoring link doesn’t change for a given device, we can think of it as being a property of the device, as well as a link included for convenience in the response message.