Network Status APIs

Integrations & APIs / Network Status APIs
Integrations & APIs Network Status APIs

Network Status APIs

quanly | 04:24 PM 15/03/2018

Tanaza provides APIs to read in real-time the status of your networks in cloud.tanaza.com.
In this document we describe the Tanaza Cloud Public REST APIs, that allow a user to get the description and the status of all the networks and access points on his Tanaza account.

Tanaza provides APIs to read in real-time the status of your networks in cloud.tanaza.com.
In this document we describe the Tanaza Cloud Public REST APIs, that allow a user to get the description and the status of all the networks and access points on his Tanaza account.


 

Authentication

 
The authentication system of the Tanaza Cloud Public REST APIs is based on tokens. If you want to use these APIs you needs to generate a token on cloud.tanaza.com.
In the account menu, access the section "APIs". 

AccountMenu



The first time a user asks for a token generation, the following values are created:
Unique user ID
Token 

By clicking on the button "Generate new token", a new token is generated. Starting from that moment on, all the previous tokens are not valid anymore. Only one token at a time can be used.
To authenticate via API, you need both user ID and token. The user ID is unique and it's always the same, while you can generate as many tokens as you want (but only the last one is valid).
The user can also disable the APIs on his account (this is the default state).
 
Endpoint 
 
To access the access point information a simple HTTP GET request needs to be performed to the following URL:
For Version 1
Endpoint:        https://cloud.tanaza.com/apis/v1/
For Version 2
Endpoint:       https://cloud.tanaza.com/apis/v2.0/

Actions
 
An action needs to be specified when accessing the API.
As for version 1 and 2.0 of the APIs, only the "status" action is available.
 
Request
 
The request is performed using the following URL structure:

Version 1
https://cloud.tanaza.com/apis/v1/USERID/TOKEN/ACTION
Supposing the user id is "hhiillmmnnooppqqrr" and the generated token is "aabbccddeeffgg", if the user wants to request the "status" action on his account the following request must be executed:
URL for GET REQUEST: https://cloud.tanaza.com/apis/v1/hhiillmmnnooppqqrr/aabbccddeeffgg/status

Version 2
https://cloud.tanaza.com/apis/v2.0/USERID/TOKEN/ACTION
Supposing the user id is "hhiillmmnnooppqqrr" and the generated token is "aabbccddeeffgg", if the user wants to request the "status" action on his account the following request must be executed:
URL for GET REQUEST: https://cloud.tanaza.com/apis/v2.0/hhiillmmnnooppqqrr/aabbccddeeffgg/status

Response
 
For each request a response with content-type "application/json" is returned with the following structure:
JSON Object properties: 
 

Property name Type Description
errorCode number If equals to 0 the request was successfully executed and the response can be found in the "payload" property.
If not equals 0 an error occurred. Please refer to the errorCode in the next paragraph.
errorMessage string Explains the error occurred and gives more details.
payload   JSON Object  It is the response payload, coded in a json object. It varies based on the action required.


"Status" Action Response V1
The "status" action allows you to know the following data about your account:
Networks
Access Points
SSIDs currently active on the Access Points
The users (client MAC addresses) that are connected to the Access Points
Status of each access point

"Status" Action Response V2.0
The "status" action allows the user to know the following data about his account:
1. Networks
2. Access Points
3. Ssids currently active on the Access Points
4. The users (client mac address) that are connected to the Access Points
5. Status of each Access Point
 

An example of the payload data structure for V1

As for the structure it contains:
A list of networks.
For each network: its label and a list of devices.
For each device: its label, its MAC address (where the first MAC address of the list is the WAN MAC address), a list of SSIDs, the timestamp of the latest packet received by Tanaza from the device (expressed in milliseconds UTC), current status of the access point (it can be "online" or "offline")
For each SSID: its label, a list of clients connected to that SSID
For each client: the client MAC address, the strenght of the signal expressed in dBm

An example of the complete response resulting data structure
Tanaza Cloud Public REST APIs allow a user to get the description and the status of all the networks and access points on his Tanaza account.

 

 

An example of the payload data structure for V2.0

As for the structure it contains:
A list of networks.
For every network: its label and a list of devices.
For every device: its label, its mac addresses (where the first mac address of the list is the wan
mac address), a list of ssids,the timestamp of the latest packet received by tanaza from the
device (expressed in milliseconds UTC), current status of the access point (can be "online" or
"offline")
For every ssid: its label, a list of clients connected to that ssid
For every client: the client mac address, the strenght of the signal expressed in dBm
This is the specification of all the fields in the JSON output, with an example.
 

Object Property type Description
Networks   array of objects (Network) Array containing objects that describe all the networks
Network label string The label assigned to the network
Network devices array of objects (Device) Array of all the devices associated to this network
Device id long Unique identifier for access point on tanaza
Device label string The label assigned to the access point
Device mac_address array of string All the mac addresses of the interfaces of the device in the following format “00:11:22:33:44:55” The first mac address is the WAN mac_address and is the one identifying the access point in tanaza
Device Status string Status of the access point, one of:
● “online” , if the access point was seen online in the last 60 seconds
● “alert” , if not in “online” state and less then 5 minutes have passed
● “offline” , it the access point was seen online the last time more then 5 minutes ago
Device last_timestamp long Last time the access point sent information or stats or was last seen. Expressed as unix time seconds.

Example: 1461644434 Stands for: 2016­04­26T04:20:34Z

All information with prefix “last_” are referring to this timestamp.
Device last_uptime long Number of minutes of uptime (power on from last reboot) of the access point, regardless of connection problems.
Device last_bytes_tx long Number of bytes transmitted by the access point.
Device last_bytes_rx long Number of bytes received  by the access point
Device last_pkts_rx long Number of packets sent by the access point
Device last_load_percentage long Number from 0 to 100, expressing the percentage of load on the access point. Higher value indicates higher load on the access point.
Device last_total_ram long Number of total available bytes of ram memory on the access point, regardless of how much is used now.
Device last_free_ram long Number of free bytes of ram memory on the access point.
Device last_used_ram long Number of used bytes of ram memory on the access point.
Device ssids array of object (Ssid) Ssids enabled on the access points with relative information
Ssid label string The broadcasting Ssid name, corrisponds to the Ssid profile name in tanaza
Ssid clients array of object (Client) List of clients connected to the ssid
Client mac string The unique mac address identifier of the client connected to the access point.
Client strength long The strength of the signal communicating with the client, expressed in dBm
Client idle_time long The amount of time the client is being idle
Client bytes_rx long Number of bytes received by the client
Client bytes_tx long Number of bytes sent by the client
Client pkts_tx long Number of packets received by the client
Client pkts_tx long Number of packets sent by the client
Client connection_time long Number of seconds the client is connected to this ssid
Client tx_retries long Number of transmission retries
Client tx_failed long Number of transmission failed



An example of the complete response resulting data structure:

User-added image



 

Based on the error code in the response, you can understand if the request was executed correctly.
 

ErrorCode Value

Description

What to do

200

Everything ok. No error occured.

The payload property contains the response.

400

Bad request. Wrong parameters specified in the request

The request was not executed correctly. Check the URL structure.

403

Authentication error

The token / user ID supplied is not valid or the user disabled the API access on its account. Or a new token was generated, invalidating the token in the request.

405

User blocked.

Contact support.

500

Request rate exceeded

Wait until the timeout of the rate exceeded ends. In the errorMessage you will find how long you should wait.

Consider that this happens only because you request too often the data from the server. 



Request Rates

The APIs are not meant to be used more than once a minute.
If two or more requests are made within the same minute, the response will the previous one (Request rate exceeded), and no updated data will be sent.
So consider to request an update only once a minute, as all the other requests will be useless.
To activate the Network API  on your account, please refer to sales@tanaza.com

 

Từ khóa :