Zetta API

A REST API specification for the Internet of Things

application/vnd.siren.zetta+json

API

Zetta provides five sections in each Zetta API response.

  • properties
  • actions
  • links
  • entities
  • class

Zetta is a grammar of the Siren hypermedia specification. See Siren for more details.

There are three resource types in Zetta.

  • device
  • server
  • root

The root resource has many servers and servers have many devices.

device

properties

The Zetta API has five reserved properties.

  • id
  • type
  • state
  • name
  • style

Zetta allows for an arbitrary number of custom properties.

id

The id property uniquely identifies a device or a server.

"properties": {
  …
  "id": "4"
  …
}

The server and device ids are used in the URL with the syntax below.

GET http://demo.zettaapi.org/servers/1/devices/4

type

The type property indicates the type of device: light, camera, robot, etc..

"properties": {
  …
  "type": "robot"
  …
}

state

The state property indicates the current state of the device, for example the robot is currently walking.

"properties": {
  …
  "state": "walking"
  …
}

name

The name property is often assigned by the end user of the device as part of the device claiming process. Below, we have robot named B-9.

"properties": {
  …
  "name": "B-9"
  …
}

style

The style property contains metadata for processing the API and rendering a user interface for the API. The style property can contain units of measure, symbols and the number of significant digits for a metric. The style property provides information like a cascading stylesheet (CSS) in the world of the UI web. The stateImage, for example, is typically a concatenation of the device type and device state, like robot-walking. The Zetta API includes a growing collection of device icons.

"properties": {
  …
  "style": {
    "stateImage": "http://www.zettaapi.org/icons/robot-walking.png",
    "backgroundColor": {"decimal": {"red": 0, "green": 35, "blue": 80}, "hex": '#002350'},
    "foregroundColor": {"decimal": {"red": 255, "green": 202, "blue": 0}, "hex": '#FFCA00'}
  }
  …
}

Custom Properties

Custom properties are device-specific attributes. The Zetta API supports an arbitrary number of custom properties. Each property can be any JSON-supported structure. To indicate the direction, speed and location of a robot, for example, one might include the custom properties below.

"properties": {
  …
  "heading": 180,
  "speed": 5,
  "location": {"latitude": 42.329557, "longitude": -83.065893}
  …
}

actions

As a true hypermedia REST API, each device provides a list of possible actions. The list of actions typically changes based on the state of the device. For example, if our robot is sitting then we can tell the robot to stand.

"actions": [{
  "name": "stand",
  "method": "POST",
  "href": "http://demo.zettaapi.org/servers/1/devices/1",
  "fields": [{
    "name": "action",
    "value": "stand",
    "type": "hidden"
}]

links

Zetta provides five reserved links.

  • logs
  • state
  • meta
  • self
  • up

Importantly, all device WebSockets are listed in the links section along with metadata and custom WebSocket streams.

logs WebSocket Stream

The logs WebSocket passes all device events from the server to the client. A client UI, for example, subscribes to the logs stream in order to keep device state and available actions synchronized with the actual state of the device.

"links": [
  …
  {
    "title": "logs",
    "rel": [
    "monitor",
    "http://rels.zettajs.io/object-stream"
    ],
    "href": "ws://demo.zettaapi.org/servers/1/events?topic=robot%2F4%2Flogs"
  }
  …
]

state WebSocket Stream

The state WebSocket stream provides information about the state for a particular device.

"links": [
  …
  {
    "title": "state",
    "rel": [
    "monitor",
    "http://rels.zettajs.io/object-stream"
    ],
    "href": "ws://demo.zettaapi.org/servers/1/events?topic=robot%2F4%2Fstate"
  }
  …
]

Custom WebSocket Streams

Custom WebSocket streams send device-specific attributes from the server to the client. There are no limits to the number of custom streams or the structure of data sent over the stream. To track the speed of a robot, one might include the custom stream below.

"links": [
  …
  {
    "title": "speed",
    "rel": [
    "monitor",
    "http://rels.zettajs.io/object-stream"
    ],
    "href": "ws://demo.zettaapi.org/servers/1/events?topic=robot%2F4%2Fspeed"
  }
  …
]

meta

The meta link shows all the possible states, transitions and other data about a device.

"links": [
  …
  {
    "rel": [
    "http://rels.zettajs.io/type",
    "describedby"
    ],
    "href": "http://demo.zettaapi.org/servers/1/meta/robot"
  }
  …
]

self

The self link is a link to the current device. This is especially helpful for clients to keep track of pagination scenarios and navigating a collection of devices.

"links": [
  …
  {
    "rel": [
    "self",
    "edit"
    ],
    "href": "http://demo.zettaapi.org/servers/1/devices/4"
  }
  …
]

up

The up link for a devices always takes the client up to the device's server. The up link for a server takes the client to the server's root.

"links": [
  …
  {
    "title": "1",
    "rel": [
    "up",
    "http://rels.zettajs.io/server"
    ],
    "href": "http://demo.zettaapi.org/servers/1"
  }
  …
]

entities

At the level of the server, the entities array holds a list of devices on the server. For example, a server with a camera and a robot would look like the response below.

"entities": [
  …
  {
    "class": ["device", "robot"],
    "rel": ["http://rels.zettajs.io/device"],
    "properties": {…},
    "links": {…}
  },
  {
    "class": ["device", "camera"],
    "rel": ["http://rels.zettajs.io/device"],
    "properties": {…},
    "links": {…}
  }
  …
]

class

The class section is an array of resource classses. For a device of type robot, the class would look like the array below.

"class": ["device", "robot"]

server

The server resource is the container which holds the devices.

class

The server always has class of type server.

"class": ["server"]

root

The root resource contains a list of devices.

root

The root resource always has a class of type root.

"class": ["root"]

Projects

Open Source Clients

Open Source Servers

Commercial Products

Icons

The Zetta API includes a community-driven collection of device icons for various device states. Check out the complete icon list on GitHub. The URL format for device icons follows the pattern below.

http://www.zettaapi.org/icons/{device-type}-{device-state}.png

http://www.zettaapi.org/icons/robot-opening-window.png

If you would like an icon that doesn't exist, please ask our community by creating a new icon request on GitHub.

License

You are free to share and adapt the Zetta API for any purpose, even commercially. The licensor cannot revoke these freedoms as long as you follow the license terms.

You must give appropriate credit to Zetta API, provide a link to the license and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use. You may not apply legal terms or technological measures that legally restrict others from doing anything the license permits.

What is Zetta API?

The Zetta API is a REST specification for the Internet of Things. Zetta's primary resource is a device. Each device is a collection of properties at a specific moment in time and a collection of actions that can transition the device from its current state to a new state. Device representations are transferred via HTTP request-response and via WebSockets for streaming data. The Zetta API is implemented on popular servers like Node.js and popular clients like iOS. Clients request device actions in order to transition the device from one state to the next. Along with traditional HTTP request and response style, each device representation also includes WebSocket streams so that changes in device state and available actions are sent from the server to the client without the need for client polling. The Zetta API is designed as a true REST client-server system where hypermedia can be the engine of application state.

Contact

We hope you find the Zetta API useful.
Feel free to get in touch if you have any questions or suggestions.

Get Connected