====== HTTP REST API ======
===== Introduction =====
KerOS comes with an HTTP REST API. It is used for:
  * Network configuration.   
  * Time configuration.
  * Gateway management (reboot, updates,restore...) 

The requests and their associated responses are detailed in the KerOS web services documentation. KerOS web services documentation corresponding to your firmware is accessible in [[wiki:resources:resources#keros_web_services_documentation|resources]] page.

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 in the documentation. 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™ i-series gateway, first, a login request with both the login and the password is necessary. When the request is successful, the gateway sends back a unique token. This token must be then used to authenticate each request. 


<note important>
Before firmware 4.1.2 (Keros web service documentation v8.0), if there is a configuration file named ''lan.config'' in the ''/etc/network/connman/directory'', this configuration file will prevent the REST API to modify the IPv4 configuration. \\
Once a manual configuration file is present, the only way to modify configuration is:
  * by editing the file. 
  * by removing the file. 
<code>
rm /etc/network/connman/lan.config
/etc/init.d/connman restart
</code>
</note>

===== 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 his needs.


==== Authentication ====

The use of the API is bound to a fresh token. Here is how you can request a new token:

<code bash>
curl -s '192.168.4.127/application/administration/login' \
  -H 'Accept: application/vnd.kerlink.iot-v1+json' \
  -X POST \
  -d '{"login":"admin","password":"pwd4admin"}' \
  -H 'Content-Type: application/vnd.kerlink.iot-v1+json' \
  | jq .
</code>

Here ''jq'' is used to prettify the JSON output so that it is readable and indented:

<code javascript>
{
  "token_type": "Bearer",
  "expiration_date": 1538169670,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1MzgxNjk2NzB9.0zM4BRqvMrorq916RJy4q_bghlK1HwrCYlZGADCdH1Q"
}
</code>

==== Ethernet configuration ====

=== Get Ethernet (LAN) configuration === 

<code bash>
curl -s '192.168.4.127/application/administration/lan' \
  -H 'Accept: application/vnd.kerlink.iot-v1+json' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1MzgxNjk2NzB9.0zM4BRqvMrorq916RJy4q_bghlK1HwrCYlZGADCdH1Q' \
  -X GET \
  -H 'Content-Type: application/vnd.kerlink.iot-v1+json' \
  | jq .
</code>

<code javascript>
{
  "ipv4_netmask": "",
  "ipv4": "dhcp",
  "ipv4_dns": "",
  "ipv4_address": "",
  "enable": true,
  "ipv4_gateway": "",
  "available": true
}
</code>

=== Set Ethernet (LAN) configuration === 

<code bash>
curl -s '192.168.4.127/application/administration/lan' \
  -H 'Accept: application/vnd.kerlink.iot-v1+json' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1MzgxNjk2NzB9.0zM4BRqvMrorq916RJy4q_bghlK1HwrCYlZGADCdH1Q' \
  -d '{"available":"true","ipv4_gateway":"192.168.4.4", "enable": true,"ipv4_address": "192.168.4.198","ipv4_dns": "","ipv4": "static","ipv4_netmask": "255.255.254.0"}' \
  -X PUT \
  -H 'Content-Type: application/vnd.kerlink.iot-v1+json' \
  | jq .
</code>