Skip to content

Client API

Jump to bottom
wwitman edited this page Feb 4, 2016 · 13 revisions

Client API

This topic is the reference for the Zetta client API. The client API is the REST-based, hypermedia API that Zetta generates for devices and that allows clients to interact with devices on the Internet over HTTP.

This reference is of particular interest to client app developers who wish to create applications that interact with devices exposed by Zetta.

The Zetta API uses Siren as its media type. More information can be found at http://sirenspec.org

Example

Here is an example response illustrating the Zetta client API. In this case, the response describes a specific device and its properties, actions, and related links. A client can crawl such responses to determine what actions a specific device is capable of performing, and execute those actions using links provided in the response itself.

{
  "class": [
    "device",
    "state_machine"
  ],
  "properties": {
    "id": "7cbf5759-4106-4985-83aa-e970fe13490d",
    "name": "State Machine Device",
    "type": "state_machine",
    "state": "on"
  },
  "actions": [
    {
      "class": [
        "transition"
      ],
      "name": "turn-off",
      "method": "POST",
      "href": "http://127.0.0.1:1337/servers/State%20Machine%20Server/devices/7cbf5759-4106-4985-83aa-e970fe13490d",
      "fields": [
        {
          "name": "action",
          "type": "hidden",
          "value": "turn-off"
        }
      ]
    }
  ],
  "links": [
    {
      "rel": [
        "self",
        "edit"
      ],
      "href": "http://127.0.0.1:1337/servers/State%20Machine%20Server/devices/7cbf5759-4106-4985-83aa-e970fe13490d"
    },
    {
      "title": "State Machine Server",
      "rel": [
        "up",
        "http://rels.zettajs.io/server"
      ],
      "href": "http://127.0.0.1:1337/servers/State%20Machine%20Server"
    },
    {
      "rel": [
        "http://rels.zettajs.io/type",
        "describedby"
      ],
      "href": "http://127.0.0.1:1337/servers/State%20Machine%20Server/meta/state_machine"
    },
    {
      "title": "state",
      "rel": [
        "monitor",
        "http://rels.zettajs.io/object-stream"
      ],
      "href": "ws://127.0.0.1:1337/servers/State%20Machine%20Server/events?topic=state_machine%2F7cbf5759-4106-4985-83aa-e970fe13490d%2Fstate"
    },
    {
      "title": "logs",
      "rel": [
        "monitor",
        "http://rels.zettajs.io/object-stream"
      ],
      "href": "ws://127.0.0.1:1337/servers/State%20Machine%20Server/events?topic=state_machine%2F7cbf5759-4106-4985-83aa-e970fe13490d%2Flogs"
    }
  ]
}

The Root URI /

Class

The class for this Zetta endpoint is "root".

Properties

None.

Links

  • A link to this endpoint.
    • Rel: "self" meaning a link to the current resource
  • A link to the server resource.
    • Rel: "http://rels.zettajs.io/server" - a link to a Zetta server representation.
  • A link to peer management for the current Zetta node.
    • Rel: "http://rels.zettajs.io/peer-management" - a link to peer management.

Actions

  • "query-devices" - Allows an API consumer to query for available devices on the particular Zetta server. Please see the section "Query Entity" for more information.
    • Parameters
      • Name: ql
        • Optional? No
        • Type: text
        • Description: The query to execute against Zetta. (CaQL link)
      • Name: server
        • Optional? Yes
        • Type: text
        • Description: Name of the Zetta server the consumer will query against.

GET /

Example Response

{
  "class": [
    "root"
  ],
  "links": [
    {
      "rel": [
        "self"
      ],
      "href": "http://127.0.0.1:1337/"
    },
    {
      "title": "localhost",
      "rel": [
        "http://rels.zettajs.io/server"
      ],
      "href": "http://127.0.0.1:1337/servers/localhost"
    },
    {
      "title": "foo",
      "rel": [
        "http://rels.zettajs.io/peer",
        "http://rels.zettajs.io/server"
      ],
      "href": "http://127.0.0.1:1337/servers/foo"
    },
    {
      "rel": [
        "http://rels.zettajs.io/peer-management"
      ],
      "href": "http://127.0.0.1:1337/peer-management"
    }
  ],
  "actions": [
    {
      "name": "query-devices",
      "method": "POST",
      "href": "http://127.0.0.1:1337/",
      "type": "application/x-www-form-urlencoded",
      "fields": [
        {
          "name": "server",
          "type": "text"
        },
        {
          "name": "ql",
          "type": "text"
        }
      ]
    }
  ]
}

The Server URI /servers/

Class

The class for this Zetta endpoint is "root".

Properties

  • "name" - Name of the Zetta server resource

Links

  • A link to this endpoint.
    • Rel: "self" - a link to the current resource
  • A web socket link to a feed of log events.
    • Rel: "monitor" - a link to a resource that monitors the current resource

Entities

A Zetta server representation will expose devices connected through it in the entities array. See Device Sub-Entities below for more information.

Actions

  • "query-devices" - Allows an API consumer to query for available devices on the particular Zetta server. Please see the section "Query Entity" for more information.
    • Parameters
      • Name: ql
        • Optional? No
        • Type: text
        • Description: The query to execute against Zetta. (CaQL link)
  • "register-device" - Allows an API consumer to register an HTTP based device.
    • Parameters
      • Name: type
        • Optional? No
        • Type: text
        • Description: The type of the device being registered with Zetta.
      • Name: id
        • Optional? No
        • Type: text
        • Description: The unique id assigned to the device.
      • Name: name
        • Optional? No
        • Type: text
        • Description: The unique name of the device.

GET /servers/localhost

Example Response

{
  "class": [
    "server"
  ],
  "properties": {
    "name": "localhost"
  },
  "actions": [
    {
      "name": "register-device",
      "method": "POST",
      "href": "http://127.0.0.1:1337/servers/localhost/devices",
      "type": "application/x-www-form-urlencoded",
      "fields": [
        {
          "name": "type",
          "type": "text"
        },
        {
          "name": "id",
          "type": "text"
        },
        {
          "name": "name",
          "type": "text"
        }
      ]
    },
    {
      "name": "query-devices",
      "method": "GET",
      "href": "http://127.0.0.1:1337/servers/localhost",
      "type": "application/x-www-form-urlencoded",
      "fields": [
        {
          "name": "ql",
          "type": "text"
        }
      ]
    }
  ],
  "links": [
    {
      "rel": [
        "self"
      ],
      "href": "http://127.0.0.1:1337/servers/localhost"
    },
    {
      "rel": [
        "monitor"
      ],
      "href": "ws://127.0.0.1:1337/servers/localhost/events%3Ftopic=logs"
    }
  ],
  "entities": [
    {
      "class": [
        "device",
        "led"
      ],
      "rel": [
        "http://rels.zettajs.io/device"
      ],
      "properties": {
        "id": "798770ad-70f0-4d7d-b8a7-28efdca6b704",
        "type": "led",
        "name": null,
        "state": "off"
      },
      "links": [
        {
          "rel": [
            "self"
          ],
          "href": "http://127.0.0.1:1337/servers/localhost/devices/798770ad-70f0-4d7d-b8a7-28efdca6b704"
        },
        {
          "title": "localhost",
          "rel": [
            "up",
            "http://rels.zettajs.io/server"
          ],
          "href": "http://127.0.0.1:1337/servers/localhost"
        }
      ]
    },
    {
      "class": [
        "device",
        "generator"
      ],
      "rel": [
        "http://rels.zettajs.io/device"
      ],
      "properties": {
        "id": "e8772322-bc43-4ce5-852a-959a7785ff34",
        "wave": -0.4999999999999903,
        "type": "generator",
        "name": "SineWave"
      },
      "links": [
        {
          "rel": [
            "self"
          ],
          "href": "http://127.0.0.1:1337/servers/localhost/devices/e8772322-bc43-4ce5-852a-959a7785ff34"
        },
        {
          "title": "localhost",
          "rel": [
            "up",
            "http://rels.zettajs.io/server"
          ],
          "href": "http://127.0.0.1:1337/servers/localhost"
        }
      ]
    }
  ]
}

Device Sub-Entity used in Server Representation

Class

The class for this entity is "device", and has an additional class of it's type.

Rel

The rel for this entity is "http://rels.zettajs.io/device".

Properties

  • "id" - The unique identifier for the device in Zetta.
  • "type" - The type of device the entity represents.
  • "name" - The unique human readable name for the device. optional
  • "state" - The current state the device is in.

Note: Any other properties exposed by the device will be listed here as well.

Links

  • A link to the full device representation.
    • Rel: "self" - a link to the full representation of the device.
  • A link to the device the server belongs to.
    • Rel: "up" - a link to the parent context of the current entity.
    • Rel: "http://rels.zettajs.io/server" - a link to a Zetta server.

Example response

{
  "class": [
    "device",
    "led"
  ],
  "rel": [
    "http://rels.zettajs.io/device"
  ],
  "properties": {
    "id": "798770ad-70f0-4d7d-b8a7-28efdca6b704",
    "type": "led",
    "name": null,
    "state": "off"
  },
  "links": [
    {
      "rel": [
        "self"
      ],
      "href": "http://127.0.0.1:1337/servers/localhost/devices/798770ad-70f0-4d7d-b8a7-28efdca6b704"
    },
    {
      "title": "localhost",
      "rel": [
        "up",
        "http://rels.zettajs.io/server"
      ],
      "href": "http://127.0.0.1:1337/servers/localhost"
    }
  ]
}

The Device URI /servers//devices/

Class

The class for this entity is "device", and has an additional class of it's type.

Properties

  • "id" - The unique identifier for the device in Zetta.
  • "type" - The type of device the entity represents.
  • "name" - The unique human readable name for the device. optional
  • "state" - The current state the device is in.

Note: Any other properties exposed by the device will be listed here as well.

Links

  • A link to the full device representation.
    • Rel: "self" - a link to the full representation of the device.
  • A link to the device the server belongs to.
    • Rel: "up" - a link to the parent context of the current entity.
    • Rel: "http://rels.zettajs.io/server" - a link to a Zetta server.

Note: Sensor streams will also have links generated for them.

GET /servers/localhost/devices/e8772322-bc43-4ce5-852a-959a7785ff34

Actions

Actions on devices are generated by their state machine. See the "Device Actions" section for more details.

Example response

{
  "class": [
    "device",
    "generator"
  ],
  "properties": {
    "id": "e8772322-bc43-4ce5-852a-959a7785ff34",
    "wave": -0.8660254037841898,
    "type": "generator",
    "name": "SineWave"
  },
  "actions": null,
  "links": [
    {
      "rel": [
        "self"
      ],
      "href": "http://127.0.0.1:1337/servers/localhost/devices/e8772322-bc43-4ce5-852a-959a7785ff34"
    },
    {
      "title": "localhost",
      "rel": [
        "up",
        "http://rels.zettajs.io/server"
      ],
      "href": "http://127.0.0.1:1337/servers/localhost"
    },
    {
      "rel": [ 
        "http://rels.zettajs.io/type",
        "describedby"
      ],
      "href": "http://zetta-cloud-2.herokuapp.com/servers/testserver/meta/led"
    },
    {
      "title": "wave",
      "rel": [
        "monitor",
        "http://rels.zettajs.io/object-stream"
      ],
      "href": "ws://127.0.0.1:1337/servers/localhost/events?topic=generator%2Fe8772322-bc43-4ce5-852a-959a7785ff34%2Fwave"
    },
    {
      "title": "logs",
      "rel": [
        "monitor",
        "http://rels.zettajs.io/object-stream"
      ],
      "href": "ws://127.0.0.1:1337/servers/localhost/events?topic=generator%2Fe8772322-bc43-4ce5-852a-959a7785ff34%2Flogs"
    }
  ]
}

Device Actions

Device actions are generated through your state machine configuration.

Name

The name of the action.

Method

The HTTP method used to access the action.

href

The link that the action runs it's method against.

fields

Inputs needed for the action.

Note: The "action" field is required every time the action is used.

Example response

{
  "name": "turn-on",
  "method": "POST",
  "href": "http://127.0.0.1:1337/servers/localhost/devices/798770ad-70f0-4d7d-b8a7-28efdca6b704",
  "fields": [
    {
      "name": "action",
      "type": "hidden",
      "value": "turn-on"
    }
  ]
}

Query Entity

The query entity is the result of using the "query-devices" action on the root or server API endpoints.

Class

The classes for this entity are "server" and "search-results"

Properties

  • "name" - The name of the server the query was issued against.
  • "ql" - The query that was issued.

Actions

  • "query-devices" - Allows an API consumer to query for available devices on the particular Zetta server.
    • Parameters
      • Name: ql
        • Optional? No
        • Type: text
        • Description: The query to execute against Zetta. (CaQL link)
  • "register-device" - Allows an API consumer to register an HTTP based device.
    • Parameters
      • Name: type
        • Optional? No
        • Type: text
        • Description: The type of the device being registered with Zetta.
      • Name: id
        • Optional? No
        • Type: text
        • Description: The unique id assigned to the device.
      • Name: name
        • Optional? No
        • Type: text
        • Description: The unique name of the device.

Links

  • A link to this endpoint.
    • Rel: "self" - a link to the current resource
  • A web socket link to a feed of log events.
    • Rel: "monitor" - a link to a resource that monitors the current resource
  • A web socket link to a feed of devices that fulfill the query as they come online
  • Rel: "http://rels.zettajs.io/query" - A web socket link to a live Zetta query

Entities

The entities that fulfill the query.

Example response

{
  "class": [
    "server",
    "search-results"
  ],
  "properties": {
    "name": "localhost",
    "ql": " where type = \"led\""
  },
  "actions": [
    {
      "name": "register-device",
      "method": "POST",
      "href": "http://localhost:1337/servers/localhost/devices",
      "type": "application/x-www-form-urlencoded",
      "fields": [
        {
          "name": "type",
          "type": "text"
        },
        {
          "name": "id",
          "type": "text"
        },
        {
          "name": "name",
          "type": "text"
        }
      ]
    },
    {
      "name": "query-devices",
      "method": "GET",
      "href": "http://localhost:1337/?ql=%20where%20type%20=%20%22led%22",
      "type": "application/x-www-form-urlencoded",
      "fields": [
        {
          "name": "ql",
          "type": "text"
        }
      ]
    }
  ],
  "links": [
    {
      "rel": [
        "self"
      ],
      "href": "http://localhost:1337/?ql=%20where%20type%20=%20%22led%22"
    },
    {
      "rel": [
        "monitor"
      ],
      "href": "ws://localhost:1337/servers/localhost/events%3Ftopic=logs"
    },
    {
      "rel": [
        "http://rels.zettajs.io/query"
      ],
      "href": "ws://localhost:1337/servers/localhost/events?topic=query%2F%20where%20type%20%3D%20%22led%22&since=1414781488226"
    }
  ],
  "entities": [
    {
      "class": [
        "device"
      ],
      "rel": [
        "http://rels.zettajs.io/device"
      ],
      "properties": {
        "id": "798770ad-70f0-4d7d-b8a7-28efdca6b704",
        "type": "led",
        "name": null,
        "state": "off"
      },
      "links": [
        {
          "rel": [
            "self"
          ],
          "href": "http://localhost:1337/servers/localhost/devices/798770ad-70f0-4d7d-b8a7-28efdca6b704"
        },
        {
          "title": "localhost",
          "rel": [
            "up",
            "http://rels.zettajs.io/server"
          ],
          "href": "http://localhost:1337/servers/localhost"
        }
      ]
    }
  ]
}

Peer Managment URI /peer-management

Class

The class for this entity is "peer-management".

Properties

None

Links

  • A link to the full device representation.
    • Rel: "self" - a link to the full representation of the device.

Actions

  • "link" - Allows an API consumer link Zetta instances with the Z2Z protocol.
    • Parameters
      • Name: url
        • Optional? No
        • Type: url
        • Description: The URL for the Zetta instance to establish a Z2Z connection to.

Entities

Entities is a list of currently connected or connecting peers. See the "Peer Sub-Entity" section for more details.

Example response

GET /peer-management

{
  "class": [
    "peer-management"
  ],
  "actions": [
    {
      "name": "link",
      "method": "POST",
      "href": "http://localhost:1337/peer-management",
      "fields": [
        {
          "name": "url",
          "type": "url"
        }
      ]
    }
  ],
  "entities": [
    {
      "class": [
        "peer"
      ],
      "properties": {
        "id": "55ae9e30-cb03-4d96-ada6-4ec024eb0d51",
        "name": "55ae9e30-cb03-4d96-ada6-4ec024eb0d51",
        "direction": "initiator",
        "status": "connected",
        "updated": 1414775744737
      },
      "actions": [
        {
          "name": "reconnect",
          "method": "POST",
          "href": "http://localhost:1337/peer-management",
          "fields": [
            {
              "name": "url",
              "type": "url",
              "value": "http://hello-zetta.herokuapp.com/"
            }
          ]
        }
      ],
      "links": [
        {
          "rel": [
            "self"
          ],
          "href": "http://localhost:1337/peer-management/55ae9e30-cb03-4d96-ada6-4ec024eb0d51"
        },
        {
          "rel": [
            "http://rels.zettajs.io/root"
          ],
          "href": "http://hello-zetta.herokuapp.com/"
        },
        {
          "rel": [
            "monitor"
          ],
          "href": "ws://hello-zetta.herokuapp.com/"
        }
      ]
    }
  ],
  "links": [
    {
      "rel": [
        "self"
      ],
      "href": "http://localhost:1337/peer-management"
    }
  ]
}

Peer Subentity

Class

The class for this entity is "peer"

Properties

  • "id" - Unique id assigned by Zetta for that instance.
  • "name" - Unique name assigned by Zetta for that instance.
  • "direction" - "initiator" if Zetta instance initiates Zetta instance. "acceptor" if Zetta instance accepted incoming Z2Z connection.
  • "status" - Current status of connection.
  • "updated" - Last known time connection state was updated.

Actions

If the "direction" property of the entity is "initiator":

  • "reconnect" - Re-initialize Z2Z connection between two Zetta instances.
    • Parameters
      • Name: url
        • Optional? No
        • Type: url
        • Description: The URL for the Zetta instance to reinitialize a Z2Z connection with.

if the "direction" property of the entity is "acceptor":

  • "disconnect" - Delete Z2Z connection between two Zetta instances.
  • "update" - Change connection between two Z2Z instances.
    • Parameters
      • Name: url
        • Optional? No
        • Type: url
        • Description: The URL for the Zetta instance to reinitialize a Z2Z connection with.

Links

  • A link to the peer representation.
    • Rel: "self" - a link to the peer representation.
  • A link to root of the peer API.
    • Rel: "http://rels.zettajs.io/root" - a link to the peer representation root API.
  • A web socket link to the updating status of the peer.
    • Rel: "monitor" - a link to a resource that monitors the current resource.

Example response

{
  "class": [
    "peer"
  ],
  "properties": {
    "id": "55ae9e30-cb03-4d96-ada6-4ec024eb0d51",
    "name": "55ae9e30-cb03-4d96-ada6-4ec024eb0d51",
    "direction": "initiator",
    "status": "connected",
    "updated": 1414775744737
  },
  "actions": [
    {
      "name": "reconnect",
      "method": "POST",
      "href": "http://localhost:1337/peer-management",
      "fields": [
        {
          "name": "url",
          "type": "url",
          "value": "http://hello-zetta.herokuapp.com/"
        }
      ]
    }
  ],
  "links": [
    {
      "rel": [
        "self"
      ],
      "href": "http://localhost:1337/peer-management/55ae9e30-cb03-4d96-ada6-4ec024eb0d51"
    },
    {
      "rel": [
        "http://rels.zettajs.io/root"
      ],
      "href": "http://hello-zetta.herokuapp.com/"
    },
    {
      "rel": [
        "monitor"
      ],
      "href": "ws://hello-zetta.herokuapp.com/"
    }
  ]
}

Device Metadata URI /servers/:server_name/meta

Class

The class for this entity is "metadata"

Properties

  • "name" - Name of the Zetta server resource.

Entities

A list of sub-Entities describing each device type the server currently knows about. Contains the type, properties of the device type, available streams, and all transitions.

Links

  • A link to the severs metadata.
    • Rel: "self"
  • A link to root of the servers API.
    • Rel: "http://rels.zettajs.io/server"
  • A web socket link to the updating list of metadata.
    • Rel: "monitor"

GET /servers/localhost/meta

Example response

{
  "class": [
    "metadata"
  ],
  "properties": {
    "name": "localhost"
  },
  "entities": [
    {
      "class": [
        "type"
      ],
      "rel": [
        "http://rels.zettajs.io/type",
        "item"
      ],
      "properties": {
        "type": "led",
        "properties": [
          "id",
          "type",
          "state"
        ],
        "streams": [
          "state"
        ],
        "transitions": [
          {
            "name": "turn-on"
          },
          {
            "name": "turn-off"
          }
        ]
      },
      "links": [
        {
          "rel": [
            "self"
          ],
          "href": "http://localhost:1337/servers/localhost/meta/led"
        }
      ]
    }
  ],
  "links": [
    {
      "rel": [
        "self"
      ],
      "href": "http://localhost:1337/servers/localhost/meta"
    },
    {
      "rel": [
        "http://rels.zettajs.io/server"
      ],
      "href": "http://localhost:1337/servers/localhost"
    },
    {
      "rel": [
        "monitor"
      ],
      "href": "ws://localhost:1337/servers/localhost/events?topic=meta"
    }
  ]
}

Type Metadata URI /servers/:server_name/meta/:type

View metadata on a specific device type.

Class

The class for this entity is "type"

Properties

  • "type" - Device type.
  • "properties" - List of properties that are set on the device type.
  • "steams" - List of streams available.
  • "transitions" - List of transitions, contains name and fields with their type.

Links

  • A link to the device type metadata.
    • Rel: "self"
  • A link back the servers metadata.
    • Rel: "collection"
    • Rel: "http://rels.zettajs.io/metadata"
  • A link that will query the server for all devices that have this devvice type.
    • Rel: "describe"
    • Rel: "http://rels.zettajs.io/instances"

GET /servers/localhost/meta/led

Example response

{
  "class": [
    "type"
  ],
  "properties": {
    "type": "led",
    "properties": [
      "id",
      "type",
      "state"
    ],
    "streams": [
      "state"
    ],
    "transitions": [
      {
        "name": "turn-on"
      },
      {
        "name": "turn-off"
      }
    ]
  },
  "links": [
    {
      "rel": [
        "self"
      ],
      "href": "http://localhost:1337/servers/localhost/meta/led"
    },
    {
      "title": "milford1",
      "rel": [
        "collection",
        "http://rels.zettajs.io/metadata"
      ],
      "href": "http://localhost:1337/servers/localhost/meta"
    },
    {
      "rel": [
        "http://rels.zettajs.io/instances",
        "describes"
      ],
      "href": "http://localhost:1337/servers/localhost?ql=where%20type%3D%22led%22"
    }
  ]
}

Need help? Visit the Zetta Discuss List !

Need help? Visit the Zetta Discuss List !

Zetta Wiki Contents

About Zetta

Videos and webcasts

Tutorials

Understanding Zetta

Writing Zetta drivers

Using streams

Reference

Projects you can build
Clone this wiki locally