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 [2018/12/24 10:33] hch |
— (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:common_resources|KerOS web services documentation]]. | ||
| - | |||
| - | A RESTful Web services-based architecture follows basic design principles: | ||
| - | |||
| - | * It exposes a tree of resources via URI. | ||
| - | * It is stateless. Each request from any client contains all required information, also, the 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 or Wirnet iFemtoCell, 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> | ||
| - | 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 its needs. | ||
| - | |||
| - | |||
| - | ==== Authentication ==== | ||
| - | |||
| - | The use of the API is bound to a fresh token. Here is how you can request for 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> | ||
| - | { | ||
| - | "available": true, | ||
| - | "ipv4_gateway": "", | ||
| - | "enable": true, | ||
| - | "ipv4_address": "", | ||
| - | "ipv4_dns": "", | ||
| - | "ipv4": "dhcp", | ||
| - | "ipv4_netmask": "" | ||
| - | } | ||
| - | </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.1545643989.txt.gz · Last modified: 2019/01/17 10:01 (external edit)
