Differences

This shows you the differences between two versions of the page.

--- wiki:restapi [2018/09/28 11:29]
ghi [Examples]
+++ — (current)
@@ Line 1: / Line 1: @@
-====== HTTP REST API ======
-===== Introduction =====
-The HTTP REST API service is used for:
-  * Network configuration.
-  * Time configuration.
-  * Gateway management (reboot, updates,restore...)
-The requests and their associated responses are detailed in the [[wiki:resources|KerOS web services documentation]].
-A RESTful Web services architecture follows basic design principles:
-  * It exposes a tree of resources via URI
-  * It is stateless. Each request from any client contains all the information necessary to service the request, and session state is held in the client.
-  * A resource is represented by an hypermedia type, for example JSON
-  * It uses HTTP methods explicitly (''GET'', ''POST'', ''PUT'', ''DELETE'', …) and other HTTP standards
-  * hypertext links to reference state
-  * hypertext links to reference-related resources
-The API version level is requested by the client using the //accept// HTTP header, for example here with API v1:
-<code>Accept: application/vnd.kerlink.iot-v1+json</code>
-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.
-To send HTTP requests to Wirnet iBTS, first, a login request with both the login and the password is necessary. When the request is successful, gateway sends back a unique token. This token must then be used in each request.
-===== Examples =====
-These examples use the command-line program curl to make HTTP requests. It is recommended to read the following examples in parallel with the 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.
-==== Authentication ====
-Request : ''login''
-This script sends a ''login'' request and extract the token from Wirnet iBTS response. If no token is received, then, the script ends. The password used for the request is the admin password (same as for the web interface).
-<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
-### INSERT BELOW THE REQUEST(S) TO BE EXECUTED ###
-</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>
-### INSERT HERE THE LOGIN SCRIPT ###
-# 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>
-### 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'                              \
-                        -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>
-### INSERT HERE THE LOGIN SCRIPT ###
-# 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>
-### INSERT HERE THE LOGIN SCRIPT ###
-# 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>
-==== 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.
-<code bash>
-### INSERT HERE THE LOGIN SCRIPT ###
-# GET RX data for all end-devices
-curl --insecure -s                                                             \
-     "$URL/application/spn/rxdata/file"                                        \
-     -H "Authorization: Bearer $TOKEN"                                         \
-     -H "Content-Type: application/vnd.kerlink.iot-v1+json"                    \
-     -o rx_data.csv
-</code>

Wirnet™ i-series

User Tools

Site Tools

Differences

Page Tools