User Tools
wiki:http_rest_api
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
wiki:http_rest_api [2018/05/04 18:03] mpe |
— (current) | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| - | ====== 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 [[wiki:resources|resources]] menu. | ||
| - | |||
| - | The other document covers all the other methods (backhaul configuration, service configuration, administration, …). It can be found in the [[wiki:resources|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. | ||
| - | |||
| - | <note important>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.</note> | ||
| - | |||
| - | ==== 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. | ||
| - | |||
| - | <code bash> | ||
| - | #! /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 | ||
| - | </code> | ||
| - | |||
| - | ==== 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 . | ||
| - | |||
| - | <code bash> | ||
| - | # Download SPN iFemtoCell configuration | ||
| - | curl --insecure -s \ | ||
| - | "$URL/application/administration/configuration" \ | ||
| - | -H "Authorization: Bearer $TOKEN" \ | ||
| - | -o spn_config.json | ||
| - | </code> | ||
| - | |||
| - | ==== 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. | ||
| - | |||
| - | <code bash> | ||
| - | #-------------------------------------------------------------------------------- | ||
| - | # 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 | ||
| - | </code> | ||
| - | ==== 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. | ||
| - | |||
| - | <code bash> | ||
| - | # 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 | ||
| - | </code> | ||
| - | |||
| - | 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. | ||
| - | |||
| - | <code bash> | ||
| - | # 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" \ | ||
| - | ) | ||
| - | </code> | ||
wiki/http_rest_api.1525449807.txt.gz · Last modified: 2020/02/21 11:53 (external edit)
Page Tools
