Document

obniz Hardware and cloud specifications.


obniz API

Let's use a hardware as API

Do Everything via API

You can fully control obniz by sending JSON via WebSocket API.
It allows you to turn IO on/off, send/receive data via UART/SPI, use BLE/OLED, etc.

This is a new way to control things from the internet.

WebSocket API in particular lets you use obniz from your HTML and bi-directional communication.
obniz.js wraps this API.

This page shows details and specifications of the API.

Endpoint

Each obniz has different API Endpoint.

WebSocket API

wss://obniz.io/obniz/{obniz_id}/ws/1

Here is an example of JavaScript usage

<!-- HTML Example -->
<html>
<body>
<script>
  // Simplest example
  var host = 'wss://obniz.io'

  function connect() {
    var socket = new WebSocket(host + '/obniz/OBNIZ_ID_HERE/ws/1');

    socket.onmessage = function (event) {
      var arr = JSON.parse(event.data);
      for (var i=0; i<arr.length; i++) {
        var obj = arr[i];
        if (obj.ws && obj.ws.redirect) {
          host = obj.ws.redirect;
          socket.onmessage = null;
          socket.close();
          connect();
        }
        if (obj.ws && obj.ws.ready) {
          socket.send(JSON.stringify([{display:{clear:true}}, {display:{text:"Works fine."}}]));
        }
      }
    }

  }

  connect();

</script>
</body>
</html>

REST API

It is also possible to post JSON via HTTP REST API, not just WebSocket API.
However, you can send but cannot receive any values from obniz via this API.

POST https://obniz.io/obniz/{obniz_id}/api/1

The requested content type must be application/JSON and the body must contain JSON object.

Here is a Curl example.

curl https://obniz.io/obniz/1234-5678/api/1 -H "Content-Type: application/json" -X POST -d '[{"display":{"clear":true, "text":"Works fine."}}]'

Security

After creating an account with obniz and going through ownership process, obniz API can be used with API keys. This is optional but recommended.
See more details on each obniz setting page. It will appear on your account page after registration.

JSON Formats

All communications on WebSocket are in JSON format.
Control obniz by sending JSON and get values by receiving JSON from obniz.

See obniz WebSocket format