wiki:restapi
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
wiki:restapi [2019/09/25 10:02] ghi |
— (current) | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| - | ====== 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#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™ Productline 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> | ||
| - | |||
| - | |||
| - | |||
wiki/restapi.1569398529.txt.gz · Last modified: 2019/09/25 10:02 by ghi
