Documentation

Getting started

The Ochno API is available to developers who wish to build applications that interact with the Ochno platform. One part is an HTTP-based REST API that offers ways to interact with the data in various ways, such as creating locations, updating floor plans and reading historical metrics. The other part is a MQTT-based real time data stream, offering live events and updates about the status of available Ochno sockets, such as power usage, sensor data and currently plugged in devices.

Gaining access

In order to make any data available you will need an account. This will determine which parts of the platform that you can interact with and what information you can retrieve.

Are you new to the Ochno platform and would like to gain access? Please contact support@ochno.com and we will get you set up with an account.

Retrieving an access token

All requests require an access token to identify you. This token is used to authorize you and check your permissions. To retrieve your token, you send a request to https://operated.ochno.com/auth/jwt with your account credentials. The returned value will be a json-formatted token value. Your token identifies who you are, so keep it safe and do not share it with anyone.

curl -X POST https://operated.ochno.com/auth/jwt \

-H ’Content-Type: application/json’ \
-d ’{”email”:”string”,”password”:”string”}’

{ ”token”: ”…” }

In following requests, the token should be passed in the Authorization header as a JWT type.

curl -X GET https://operated.ochno.com/api/companies \

-H ’Authorization: JWT {access-token}’

If you want the platform to remove one of your tokens you can request to be logged out.

curl -X GET https://operated.ochno.com/auth/logout \

-H ’Authorization: JWT {access-token}’

Exploring data

Using your token, you open the platform for exploration, such as your retrieving companies, managing floor plans and listening to Ochno sockets. To find out everything you can explore, see the full reference.

Everything is JSON

The API is built to consume and produce JSON formatted data. This means that all the data that is returned from the API will look something like this:

{
”id”: ”string”,
”data”: {},
”hwId”: ”string”,
”floorPlanId”: ”string”,
”name”: ”string”
}

If your API endpoint requires a request body, it should be sent as JSON too.

Example: Changing a company name

Let’s say that you have noticed that your company name has been misspelled and would like to change that. First, you need to figure out the id of that company. In the full reference you will find the correct API endpoint to get a list of all companies. Using curl it would look something like this:

curl -X GET https://operated.ochno.com/api/companies \

-H ’Accept: application/json’ \ -H ’Authorization: JWT {access-token}’

And the return value will be a JSON string with an array of company objects, such as this:

[
{
”id”: ”a11iNc3p0”,
”name”: ”Ochno”,
”type”: ”Building Owner”,
”logotype”: ”https://ochno.com/logotype.png”,
”website”: ”https://ochno.com/”
},
{
”id”: ”r2d2i5b43”,
”name”: ”Goople”,
”type”: ”Building Tenant”
}
]

To change a company name you need to replace the entire content of the company. To do this you will use the endpoint https://operated.ochno.com/api/companies/{id} but replace the {id} with your company’s id: r2d2i5b43. Notice that we do a PUT request and not a GET request, the url is the same, but the action is not. PUT allows us to replace the data, which GET does not. In other words, you will send JSON looking like this:

curl -X PUT https://operated.ochno.com/api/companies/r2d2i5b43 \
-H ’Content-Type: application/json’ \
-H ’Accept: application/json’ \
-H ’Authorization: JWT {access-token}’ \
-d ’{”name”:”Goodle”,”type”:”Building Tenant”}

As a response you should get an OK status value, with data of what the company values are now:

{
”id”: ”r2d2i5b43”,
”name”: ”Goodle”,
”type”: ”Building Tenant”,
”logotype”: ”https://example.com/logotype.png”,
”website”: ”https://example.com/”
}

If you try this example but your response is something other than an OK, there could be multiple reasons; the id could have been misspelled, there could be missing required data in the request, or your user might not have the permission to make changes to the company object. To learn more about these response codes, see the full reference.

Most of the Ochno API is very similar to this example and you can apply these techniques to the other parts of it. Certain endpoints also allow you to send url parameters to specify exactly what you want to retrieve.

Example: Setting up a real time MQTT data stream

Through the API you can get the latest data about the devices connected to your Ochno sockets. However, polling the platform is this is not a recommended way to make sure you have the most recent information about your devices. Instead you should set up a real time MQTT data stream.

These streams are setup on a company level, and they require a different access token than your JWT. The API endpoint is https://operated.ochno.com/api/companies/{id}/iotAccess. Let’s say you want to connect to the stream of the company in the previous example, where the company had the id r2d2i5b43

curl -X GET https://operated.ochno.com/api/companies/r2d2i5b43/iotAccess \
-H ’Accept: application/json’ \
-H ’Authorization: JWT {access-token}’

The response is an MQTT access configuration that you use to connect to your real time data stream. The credentials will be valid for one hour, after that it is necessary to request new ones.

{
”accessKeyId”: ”string”,
”secretKey”: ”string”,
”sessionToken”: ”string”,
”expiration”: ”string”,
”region”: ”string”,
”host”: ”string”
}

What MQTT client you use to connect to the stream is up to you. A selection of useful SDKs to make it easy for you can be found here.

After you get the connection set up, it is possible to listen to port updates. These messages will be published on the topic /ports/<companyId>/<locationId>/<hubId>/<portId> which means that you can subscribe to a single port, or a group of ports by using the catch-all ‘#’. As an example, let’s listen to all the ports of our company (how you do this will depend on how your MQTT connection is set up):

MQTT.subscribe(’/ports/r2d2i5b43/#’);

The company ports will now start sending their messages to your MQTT client and how you listen to them and process the data is up to you.

Javascript example: Setting up and managing MQTT data stream

This example shows you how to set up an MQTT stream using Javascript in an ES6 environment. It will go through the steps from logging in and retrieving access keys, to live management of port data.

The following packages will be used:

import axios from 'axios';
import awsIot from 'aws-iot-device-sdk';

// Retrieve the jwt access token for the user to be able to authorize ourselves.
axios
.post('/auth/jwt', {
email: 'email@example.com',
password: 'Longer passwords are more secure than a horse',
})
.then((res) => {
// User token received.
// This can be saved on the client to use in multiple api calls,
// but in this example it is only used for the next one.
const userToken = res.data.token;

// Retrieve the access token for the MQTT data stream.
return axios.get(`/api/companies/r2d2i5b43/iotAccess`, {
headers: {
Authorization: 'JWT ' + userToken,
},
});
})
.then((res) => {
// These response hold the access keys and info about where to connect.
const iotCredentials = res.data;

// Connect to the MQTT stream.
const client = awsIot.device(iotCredentials);

// Listen to messages from all the ports of the company.
// The # is a catch all and can be placed in other parts of the topic too.
client.subscribe('/ports/r2d2i5b43/#');

// This is the function that runs when messages are received.
client.on('message', (topic, message) => {
// message is a Uint8Array, use toString to get it as an actual string.
// The string should be a JSON, parse it into object form.
const payload = JSON.parse(message.toString());

// In this example the message is printed to the console,
// but this is where to add your code that operates on the MQTT stream.
console.log(topic, payload);
});

// When a connection fails.
client.on('error', (error) => {
// In this example the error is simply printed to console.
console.warn(error);
});

// See more events here: https://github.com/mqttjs/MQTT.js/blob/master/README.md#client

// Publish an action telling a port to change light level:
client.publish('/action/r2d2i5b43///', JSON.stringify({
id: '',
data: {
portId: '',
device: {
lamp: {
level: 10,
},
},
},
}));

// When the connection is no longer needed, make sure to end it:
// client.end();
});

Boka demo

Join Ochno!