API Documentation

VariPass API is simple and streamlined, allowing you to connect to it as easily as possible. The API is based around JSON, and comes down to sending and receiving JSON payloads. Additionally, the system allows you to connect to our WebSocket to receive update notifications live as they happen. This document explains all of the API features in detail.

Navigation:

API Server

API server URL:

https://api.varipass.org

As we explained earlier, the API is based around exchanging JSON payloads, although it does support different types of transports as well. Our API server is located at the web address above, and the URL supports both HTTP and HTTPS connections. We would advise you to use HTTPS however, mostly for security reasons. You can submit requests to the API server in three different ways, mostly because there is no guarantee that all devices and softwares will support all HTTP request types. The following examples show how you would request to read a value of some variable.

An HTTP POST request with Content-type: application/json header requires the following as content of the request:

{
    "key": "l9VvtFztnilpPcfQ",
    "action": "read",
    "id": "4OpGXF48"
}

An HTTP POST request with Content-type: application/x-www-form-urlencoded header requires the following key-value pairs as form data:

key=l9VvtFztnilpPcfQ&action=read&id=4OpGXF48

An HTTP GET request requires the following key-value pairs as GET parameters:

?key=l9VvtFztnilpPcfQ&action=read&id=4OpGXF48

Every sent request will produce a response from the server. Most of the responses will arrive as another JSON payload, but they may also arrive in a simplified format if the correct API action is sent. We have created the simplified format in case it is too complex to parse the JSON response on a certain device or software. Note that all responses will return the result field which stores the result of the API request as a string which you can read. Below are examples for the two different response types.

JSON response:

{
    "result": "success",
    "value": 25.3,
    "time": 1485383174,
    "current": 1485383186
}

Simplified response:

success|25.3

Result Field

The API stores the result of an API request in the result field. Most of the time, the result will simply be success, which means that the API request has been successfully executed. However, it can also return errors. Below is a list of all possible results.

API Actions

This section deals with all of the different API actions you can request from our website. We are providing an example request and response payload for every action type, along with all parameters explained. For simplicity, all examples are using HTTP POST.

Standard request parameters:

Standard response parameters:

The parameters above are standard and used in every API request, so they will not be mentioned again from this point.

create Create Variable

This action will create a new variable in your account. You can use it if you need to dynamically create them without using our Dashboard. This action cannot be requested if you lock your variables in your account settings.

Request example:

{
    "key": "l9VvtFztnilpPcfQ",
    "action": "create",
    "type": "float",
    "name": "Temperature",
    "description": "Temperature measured using a sensor.",
    "unit": "°C",
    "graph": true,
    "perc": true,
    "max": 40,
    "expire": 86400
}

Required parameters:

Optional parameters:

Response example:

{
    "result": "success",
    "id": "4OpGXF48"
}

Parameters:

edit Edit Variable Details

This action will edit the details of a certain variable already present on your account. This action cannot be requested if you lock your variables in your account settings.

Request example:

{
    "key": "l9VvtFztnilpPcfQ",
    "action": "edit",
    "id": "4OpGXF48",
    "type": "int",
    "name": "Humidity",
    "description": "Humidity measured by the sensor.",
    "unit": "%",
    "graph": true,
    "perc": false,
    "max": 0,
    "expire": 86400
}

Required parameters:

Optional parameters:

Response example:

{
    "result": "success"
}

info Return Variable Info

This action will return all variable's parameters that were set using the create or edit actions.

Request example:

{
    "key": "l9VvtFztnilpPcfQ",
    "action": "info",
    "id": "4OpGXF48"
}

Required parameters:

Response example:

{
    "result": "success",
    "type": "int",
    "name": "Humidity",
    "description": "Humidity measured by the sensor.",
    "unit": "%",
    "graph": true,
    "perc": false,
    "max": 0,
    "expire": 86400,
    "cooldown": 60
}

Parameters:

delete Delete Variable

This action will irreversibly delete a variable from your account. This action cannot be requested if you lock your variables in your account settings.

Request example:

{
    "key": "l9VvtFztnilpPcfQ",
    "action": "delete",
    "id": "MzZE5Bwn"
}

Required parameters:

Response example:

{
    "result": "success"
}

list List All Variables

This action returns a list of all variables on someone's account associated with the passed key.

Request example:

{
    "key": "l9VvtFztnilpPcfQ",
    "action": "list"
}

Response example:

{
    "result": "success",
    "list": [ 
            "4OpGXF48",
            "wmPVzYn7",
            "uxSNejyi"
        ]
}

Parameters:

read Read From Variable

This action returns the most recent value stored in a variable.

Request example:

{
    "key": "l9VvtFztnilpPcfQ",
    "action": "read",
    "id": "4OpGXF48"
}

Required parameters:

Response example:

{
    "result": "success",
    "value": 48,
    "time": 1485613580,
    "current": 1485613614
}

Parameters:

sread Simple Read From Variable

This action returns the most recent value stored in a variable. It is similar to the previous one, but it returns a simple string instead of a JSON payload. The action is thus more limited, but can be used in environments where parsing JSON is not be viable.

Request example:

{
    "key": "l9VvtFztnilpPcfQ",
    "action": "sread",
    "id": "4OpGXF48"
}

Required parameters:

Response example:

success|48

The returned value is stored after the | symbol.

history Read Variable History

This action returns an array of values stored in a varaible's history. This can be useful if you want to plot graphs using the data. Useful only if the expire parameter of the variable is set to something other than 0.

Request example:

{
    "key": "l9VvtFztnilpPcfQ",
    "action": "history",
    "id": "4OpGXF48"
}

Required parameters:

Response example:

{
    "result": "success",
    "history": [ 
            { "value": 48, "time": 1485613580 },
            { "value": 47, "time": 1485613520 },
            { "value": 46, "time": 1485613460 },
            { "value": 44, "time": 1485613400 } 
        ],
    "current": 1485613614
}

Parameters:

write Write To Variable

This action writes a value to a variable. The value will automatically be added to the variable's history as well if the expire parameter of the variable is set to something other than 0.

Request example:

{
    "key": "l9VvtFztnilpPcfQ",
    "action": "write",
    "id": "4OpGXF48",
    "value": 50
}

Required parameters:

Response example:

{
    "result": "success"
}

swrite Simple Write To Variable

This action writes a value to a variable. It is similar to the previous one, but it returns a simple string instead of a JSON payload.

Request example:

{
    "key": "l9VvtFztnilpPcfQ",
    "action": "swrite",
    "id": "4OpGXF48",
    "value": 50
}

Required parameters:

Response example:

success

all Return All Data

This action returns all data stored on someone's account associated with the passed key. The data includes a list of all variables, along with the history of each.

Request example:

{
    "key": "l9VvtFztnilpPcfQ",
    "action": "all"
}

Response example:

{
    "result": "success",
    "list": [
        {
            "id": "4OpGXF48",
            "type": "int",
            "name": "Humidity",
            "description": "Humidity measured by the sensor.",
            "unit": "%",
            "graph": true,
            "perc": false,
            "max": 0,
            "expire": 86400,
            "cooldown": 60,
            "history": [
                    { "value": 48, "time": 1485613580 },
                    { "value": 47, "time": 1485613520 },
                    { "value": 46, "time": 1485613460 },
                    { "value": 44, "time": 1485613400 } 
                ]
        },
        {
            "id": "wmPVzYn7",
            "type": "string",
            "name": "Bulletin",
            "description": "Text shown on the LCD.",
            "unit": "",
            "graph": false,
            "perc": false,
            "max": 0,
            "expire": 0,
            "cooldown": 1,
            "history": [
                    { "value": "VariPass is awesome!", "time": 1485013820 }
                ]
        },
        {
            "id": "uxSNejyi",
            "type": "bool",
            "name": "Light Toggle",
            "description": "Toggle for the light in the room.",
            "unit": "",
            "graph": true,
            "perc": false,
            "max": 0,
            "expire": 3600,
            "cooldown": 60,
            "history": [
                    { "value": false, "time": 1485613572 },
                    { "value": true, "time": 1485613414 },
                    { "value": false, "time": 1485613159 },
                    { "value": true, "time": 1485612277 },
                    { "value": false, "time": 1485610180 },
                ]
        }
    ],
    "current": 1485613614
}

The response is made up of three different actions: list, info and history. Considering that the response parameters in those actions are identical to these, there is no need to explain them in detail. Please refer to those actions instead.

transfer Transfer Variable Ownership

This action will transfer a variable from the account associated with the passed API key, to the account associated with the targeted email address. This action is irreversible, unless the new owner transfers it back. Note that the target account has to enable transfers in their account settings. This action cannot be requested if you lock your variables in your account settings.

Request example:

{
    "key": "l9VvtFztnilpPcfQ",
    "action": "transfer",
    "id": "wmPVzYn7",
    "target": "new.owner@varipass.org"
}

Required parameters:

Response example:

{
    "result": "success"
}

Example API Client

Building an API client is extremely easy. Below is an example code for a JavaScript client which returns the value of a certain variable from the API. The client uses an XMLHttpRequest object to create a payload and then send it. Upon receiving, it parses the input to a native object and does something with the returned value. In this case, the client will simply write the output to the console.

// Set URL to the API server.
var url = "https://api.varipass.org";

// Prepare the payload.
var payload = {
        "key": "l9VvtFztnilpPcfQ",
        "action": "read",
        "id": "MzZE5Bwn"
    };

// Create a new XMLHttpRequest.
var xhr = new XMLHttpRequest();

// Prepare parameters for POST with JSON.
xhr.open("POST", url, true);
xhr.setRequestHeader("Content-type", "application/json");

// Handle receiving of response.
xhr.onreadystatechange = function () { 
    if (xhr.readyState == 4 && xhr.status == 200) {
        // Parse the response to a usable object.
        var response = JSON.parse(xhr.responseText);

        /*
        Do something with the data.
        Here we are just printing the value to console.
        */
        console.log(response.value);
    }
}

// Send the payload.
xhr.send(JSON.stringify(payload));

WebSocket Server

WebSocket server URL:

wss://api.varipass.org:443/ws

In addition to the API, we also run a WebSocket server which you can use to receive alerts whether a variable has been updated on your account. The URL and port of our server is shown above and uses WSS (Secure WebSockets). This can be highly useful as it eleminates the need to constantly send actions to our API. Send them only when you need to instead! The API actions that send a refresh notification through the WebSocket are: create, edit, destroy, write, swrite and transfer.

The WebSocket server is based around athenticating, and then exchanging different messages. Below is the list of messages currently used along with their responses.

Messages

Example WebSocket Client

Building a WebSocket client that will interract with our server is also easy. Below is an example JavaScript code for a WebSocket client that will connect to our server, keep the connection alive, and do something every time the refresh message is received. In case of a diconnect, the client will also attempt to reconnect.

// Set URL to the WebSocket server.
var url = "wss://api.varipass.org:443/ws";
// Set your API key.
var key = "l9VvtFztnilpPcfQ";

// Used to control the ping timeouts.
var timeoutPing;

// Creates a new WebSocket and manages it.
function wsStart() {
    // Create the WebSocket connection.
    socket = new WebSocket(url);

    // Handle the opening of the socket.
    socket.onopen = function(event) {
        socket.send("key " + key);  
    };

    // Handle the disconnect of the socket.
    socket.onclose = function(event) {
        window.clearTimeout(timeoutPing);
        window.setTimeout(function() {
            wsStart();
        }, 1000);   
    };

    // Handle messages sent by the server.
    socket.onmessage = function(event) {
        var message = event.data;

        if (message == "ok") {
            timeoutPing = setTimeout(wsPing, 10000);
        }
        else if (message == "pong") {
            timeoutPing = setTimeout(wsPing, 10000);
        }
        else if (message == "refresh") {

            /*
            Handle the API refresh call here.
            Use API actions "read", "sread", "history" or "all".
            Here we are just printing the message to console.
            */
            console.log(message);
        }

    };

    // Handle any errors that occur.
    socket.onerror = function(error) {
        console.log("WebSocket Error. " + error);
    };
}

// Sends a ping message to the server.
function wsPing() {
    socket.send("ping");
}

// Start the client.
wsStart();

Demo API Client

You need to sign in before you can use the demo API client. You may sign in here.

Back to top

VariPass © 2018 CelesTek
Website designed by Thorinair
v1.0.2

VariPass uses cookies to improve your experience.