Introduction
Firmware management:
LoRa network management
Interfaces:
Gateway administration
Support and resources:
User Tools
Sidebar
wiki:http_rest_api
This is an old revision of the document!
Table of Contents
HTTP REST API
Introduction
The HTTP REST API service is used to:
- Get received data.
- Push data to be transmitted.
- Manage the fleet (add, get, delete end-devices).
- Configure the gateway (set, get value).
- Update the gateway (update, license, system).
- Get the logs.
All the features of the SPN web interface use this service.
The requests and their associated responses are detailed in two 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.
One document covers all the methods relative to the LoRa packets/end-devices/configuration. It can be found in the resources menu.
The other document covers all the other methods (backhaul configuration, service configuration, administration, …). It can be found in the resources menu.
To send HTTP requests to SPN, first, a login request with both the login and the password is necessary. When the request is successful, 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 requests documentation.
These examples are presented as is. They are not written to cover every possible exception. It is up to the user to adapt them to its needs.
The following examples have been written with the SPN firmware v1.1.1 documentation. The requests might differ a bit if another version is used. Refer to the documentation to get the exact requests.
Authentication
Request : login
This script sends a login request and extract the token from SPN response. If no token is received, then, the script ends.
#! /bin/bash URL=https://klk-wifc-03002e #-------------------------------------------------------------------------------- # Request to connect to iFemtoCell SPN. # 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"}' \ --insecure -s \ ) #-------------------------------------------------------------------------------- # extract the token from the server's reponse # (Requires the json parser "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
Configuration download
Request: downloadConfiguration
This request asks 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 .
# Download SPN iFemtoCell configuration curl --insecure -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 SPN (spn_config.json). This request uses a multipart/form-data to upload the configuration file to SPN.
#-------------------------------------------------------------------------------- # 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' \ -i --insecure -s \ -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: addEndpoint
This request sends a JSON array containing every parameter required to add a new end-device to SPN. It then checks if the request is a success.
# Add an end-device and search for the string "201 Created" ADD_DEVICE_RESULT=$(curl -i --insecure -s \ "$URL/application/spn/endpoint" \ -H "Authorization: Bearer $TOKEN" \ --data-binary '[{"activation_type":"OTAA", "class":"A","dev_eui":"0123456789123457", "app_eui":"0000000000000000", "app_key":"12345678912345678912345678912345", "dev_addr":"", "nwks_key":"", "apps_key":"", "rx_window":3, "rx_frequency":869525000, "rx_datarate":0}]' \ | 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.
# Add an end-device and search for the string "201 Created" ADD_DEVICE_RESULT=$(curl -i --insecure -s \ "$URL/application/spn/endpoint" \ -H "Authorization: Bearer $TOKEN" \ --data-binary '@end-device.json' \ | grep "201 Created" \ )
wiki/http_rest_api.1525449807.txt.gz · Last modified: 2020/02/21 11:53 (external edit)
