docs/JsonRpcHowTo.md

   1 # HowTo: Using the JSON-RPC API
   2
   3 See [online wiki](https://github.com/openwrt/luci/wiki/JsonRpcHowTo) for latest version.
   4
   5 LuCI provides some of its libraries to external applications through a [JSON-RPC](https://en.wikipedia.org/wiki/JSON-RPC) API.
   6 This Howto shows how to use it and provides information about available functions.
   7
   8 See also
   9 * wiki [rpcd](https://openwrt.org/docs/techref/rpcd)
  10 * wiki [ubus](https://openwrt.org/docs/techref/ubus)
  11
  12 ## Basics
  13 To enable the API, install the following package and restart `uhttpd`:
  14
  15 ```bash
  16 opkg install luci-mod-rpc luci-lib-ipkg luci-compat
  17 /etc/init.d/uhttpd restart
  18 ```
  19
  20 LuCI comes with an efficient JSON De-/Encoder together with a JSON-RPC-Server which implements the JSON-RPC 1.0 and 2.0 (partly) specifications.
  21 The LuCI JSON-RPC server offers several independent APIs.
  22 Therefore you have to use **different URLs for every exported library**.
  23 Assuming your LuCI-Installation can be reached through `/cgi-bin/luci`, any exported library can be reached via `/cgi-bin/luci/rpc/LIBRARY`.
  24
  25
  26 ## Authentication
  27 Most exported libraries will require a valid authentication to be called with.
  28 If you get an `HTTP 403 Forbidden` status code you are probably missing a valid authentication token.
  29 To get such a token you have to call the `login` method of the RPC-Library `auth`.
  30 Following our example from above this login function would be provided at `/cgi-bin/luci/rpc/auth`.
  31 The function accepts 2 parameters: `username` and `password` (of a valid user account on the host system) and returns an authentication token.
  32
  33 Example:
  34 ```sh
  35 curl http://<hostname>/cgi-bin/luci/rpc/auth --data '
  36 {
  37   "id": 1,
  38   "method": "login",
  39   "params": [
  40     "youruser",
  41     "somepassword"
  42   ]
  43 }'
  44 ```
  45
  46 response:
  47 ```json
  48 {"id":1,"result":"65e60c5a93b2f2c05e61681bf5e94b49","error":null}
  49 ```
  50
  51 If you want to call any exported library which requires an authentication token you have to append it as an URL parameter auth to the RPC-Server URL.
  52 E.g. instead of calling `/cgi-bin/luci/rpc/LIBRARY` you should call `/cgi-bin/luci/rpc/LIBRARY?auth=TOKEN`.
  53
  54 If your JSON-RPC client is Cookie-aware (like most browsers are) you will receive the authentication token also with a session cookie and probably don't have to append it to the RPC-Server URL.
  55
  56
  57 ## Exported Libraries
  58 ### uci
  59 The UCI-Library `/rpc/uci` offers functionality to interact with the Universal Configuration Interface.
  60
  61 **Exported Functions:**
  62 * [(string) add(config, type)](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.model.uci.html#Cursor.add)
  63 * [(integer) apply(config)](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.model.uci.html#Cursor.apply)
  64 * [(object) changes([config])](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.model.uci.html#Cursor.changes)
  65 * [(boolean) commit(config)](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.model.uci.html#Cursor.commit)
  66 * [(boolean) delete(config, section[, option])](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.model.uci.html#Cursor.delete)
  67 * [(boolean) delete_all(config[, type])](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.model.uci.html#Cursor.delete_all)
  68 * [(array) foreach(config[, type])](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.model.uci.html#Cursor.foreach)
  69 * [(mixed) get(config, section[, option])](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.model.uci.html#Cursor.get)
  70 * [(object) get_all(config[, section])](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.model.uci.html#Cursor.get_all)
  71 * [(mixed) get_state(config, section[, option])](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.model.uci.html#Cursor.get)
  72 * [(boolean) revert(config)](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.model.uci.html#Cursor.revert)
  73 * [(name) section(config, type, name, values)](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.model.uci.html#Cursor.section)
  74 * [(boolean) set(config, section, option, value)](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.model.uci.html#Cursor.set)
  75 * [(boolean) tset(config, section, values)](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.model.uci.html#Cursor.tset)
  76
  77 Example:
  78 ```sh
  79 curl http://<hostname>/cgi-bin/luci/rpc/uci?auth=yourtoken --data '
  80 {
  81   "method": "get_all",
  82   "params": [ "network" ]
  83 }'
  84 ```
  85
  86 ### fs
  87 The Filesystem library `/rpc/fs` offers functionality to interact with the filesystem on the host machine.
  88
  89 **Exported Functions:**
  90
  91 * [Complete luci.fs library](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.fs.html)
  92
  93 **Note:** All functions are exported as they are except for `readfile` which encodes its return value in [Base64](https://en.wikipedia.org/wiki/Base64) and `writefile` which only accepts Base64 encoded data as second argument.
  94 Note that both functions will only be available when the `luasocket` packet is installed on the host system.
  95
  96 ### sys
  97 The System library `/rpc/sys` offers functionality to interact with the operating system on the host machine.
  98
  99 **Exported Functions:**
 100 * [Complete luci.sys library](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.sys.html)
 101 * [Complete luci.sys.group library](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.sys.group.html) prefixing the method name with `group.methodname`.
 102 * [Complete luci.sys.net library](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.sys.net.html) prefixing the method name with `net.methodname`.
 103 * [Complete luci.sys.process library](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.sys.process.html) prefixing the method name with `process.methodname`.
 104 * [Complete luci.sys.user library](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.sys.user.html) with prefix `user`.
 105 * [Complete luci.sys.wifi library](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.sys.wifi.html) with prefix `wifi`.
 106
 107 Example:
 108 ```sh
 109 curl http://<hostname>/cgi-bin/luci/rpc/sys?auth=yourtoken --data '
 110 {
 111   "method": "net.conntrack"
 112 }'
 113 ```
 114
 115 ### ipkg
 116 The IPKG library `/rpc/ipkg` offers functionality to interact with the package manager (IPKG or OPKG) on the host machine.
 117
 118 **Exported Functions:**
 119 * [Complete luci.model.ipkg library](https://htmlpreview.github.io/?https://raw.githubusercontent.com/openwrt/luci/master/docs/api/modules/luci.model.ipkg.html)
 120