====== HTTP REST API ======
===== Introduction =====
The HTTP REST API service is used to:
* Manage end-devices fleet
* Manage gateway fleet
* Receive frames from end-devices
* Send frames to end-devices
* Configure the gateway
* Update and add license
* Debug / troubleshoot the gateway
All the features of the Wanesy SPN web interface use this service.
The requests and their associated responses are detailed in 2 documents. For each method, the method name, the URL, the content type and the content of the requests/responses are described. When the expected content is a JSON array, each field of the array is defined at the end of the document. Documents are available in [[.:..:support:resources|resources]] page.
To send HTTP requests to Wanesy SPN, first, a login request with both the login and the password is necessary. When the request is successful, Wanesy SPN sends back a unique token. This token must then be used in each request. The token is usable for 12 hours.
===== Examples =====
A few examples are presented hereunder to demonstrate the main types of requests. The following scripts are bash scripts that use the command ''curl''. However, any other language could be used.
It is recommended to read the following examples in parallel with the request documentation.
These examples are presented as-is. They are not written to cover every possible exception. It is up to the users to adapt them to their needs.
==== Authentication ====
Request: ''login''
This script sends a ''login'' request and extracts the token from the Wanesy SPN response. If no token is received, then, the script ends.
#! /bin/bash
URL=http://klk-wifc-03002e
#--------------------------------------------------------------------------------
# Request to connect to SPN gateway.
# SPN will send back a response with a token.
# This token is used to authenticate all the other requests.
# The response is stored in the variable "LOGIN_RESULT"
#-------------------------------------------------------------------------------
LOGIN_RESULT=$(curl "$URL/application/administration/login" \
--data-binary '{"login":"spn","password":"spnpwd"}' \
)
#--------------------------------------------------------------------------------
# extract the token from the server's reponse
# (Requires the json parser "jq" , sudo apt install jq)
#--------------------------------------------------------------------------------
TOKEN=$(jq .token <<< $LOGIN_RESULT |tr -d '"')
# Check if a token has been received
if [[ $TOKEN == "null" || $TOKEN = "" ]]; then
echo authentication failed
exit
fi
### INSERT BELOW THE REQUEST(S) TO BE EXECUTED ###
==== Configuration download ====
Request: ''downloadConfiguration''
This request asks Wanesy SPN to send back its configuration. Except for the token, no particular content is required. The configuration is then stored in the ''spn_config.json'' file.
### INSERT HERE THE LOGIN SCRIPT ###
# Download SPN gateway configuration
curl -s \
"$URL/application/administration/configuration" \
-H "Authorization: Bearer $TOKEN" \
-o spn_config.json
==== Configuration upload ====
Request: ''uploadConfiguration''
This request uploads a new configuration file to Wanesy SPN (''spn_config.json''). This request uses a ''multipart''/''form-data'' to upload the configuration file to Wanesy SPN.
### INSERT HERE THE LOGIN SCRIPT ###
#--------------------------------------------------------------------------------
# Upload a configuration file to SPN.
# Then, parse the request header to check if the request is succesfull (204)
#--------------------------------------------------------------------------------
UPLOAD_RESULT=$(curl "$URL/application/administration/configuration" \
-H "Authorization: Bearer $TOKEN" \
-F file='@spn_config.json' \
-H 'Expect:' \
| grep "204 No Content" \
)
# Check if the configuration has been successfully uploaded
if [[ -z $UPLOAD_RESULT ]]; then
echo Configuration file not uploaded
else
echo Configuration file uploaded
fi
==== End-device registration ====
Request: ''addEndDevice''
This request sends a JSON array containing every parameter required to add a new end-device to Wanesy SPN. It then checks if the request is a success.
### INSERT HERE THE LOGIN SCRIPT ###
# Add an end-device and search for the string "201 Created"
ADD_DEVICE_RESULT=$(curl -s \
"$URL/application/spn/end_devices" \
-H "Authorization: Bearer $TOKEN" \
--data-binary '{
"activation_type": "OTAA",
"dev_eui": "0122226789123457",
"app_eui": "0000000000000000",
"app_key": "12345678912345678912345678912345",
"dev_addr": "",
"nwks_key": "",
"apps_key": "",
"end_device_parameters": {
"rx_window": 3,
"rx_frequency": 869525000,
"rx_datarate": 0,
"class": "A"
}
}' \
| grep "201 Created" \
)
# Check if the end-device has been successfully added
if [[ -z $ADD_DEVICE_RESULT ]]; then
echo End-device not created
else
echo End-device successfully added
fi
The previous script uses hard-coded values for the end-device configuration, but the same could be done with a JSON file as shown in the following example.
This script fills the ''--data-binary'' parameter by the content of the ''end-device.json'' file. This file, obviously, contains the JSON array required to add an end-device.
### INSERT HERE THE LOGIN SCRIPT ###
# Add an end-device and search for the string "201 Created"
ADD_DEVICE_RESULT=$(curl -s \
"$URL/application/spn/end_devices" \
-H "Authorization: Bearer $TOKEN" \
--data-binary '@end-device.json' \
| grep "201 Created" \
)
==== RX data download ====
Request: ''downloadRxdata''
This request downloads the RX data from all registered end-devices. Frames are stored in the ''rx_data.csv'' file.
### INSERT HERE THE LOGIN SCRIPT ###
# GET RX data for all end-devices
curl -s \
"$URL/application/spn/rx_data/file" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/vnd.kerlink.iot-v1+json" \
-o rx_data.csv
===== HTTPS =====
HTTP is used by default on HTTP REST API and web user interface. To enable HTTPS, use this [[.:webaw_enable_https|procedure]].