mirror of
https://github.com/openwrt/luci.git
synced 2026-04-15 10:51:51 +00:00
44fd0155ff
- style with clean-jsdoc-theme (supports dark mode) - add tutorials (jaguar has a problem with this structure) - move doc gen stubs to doc_gen folder This change moves the generated JS API docs from /luci/jsapi to /luci via README.md which forms the index, and shall point to a generated html file which exists. It currently points to LuCI.html, which depends on JSDoc naming conventions. So it's possible the link can break if modules change names. But the TOC is always valid. Signed-off-by: Paul Donald <newtwen+github@gmail.com>
78 lines
2.7 KiB
Markdown
78 lines
2.7 KiB
Markdown
# Using the JSON-RPC API
|
|
|
|
LuCI provides some of its libraries to external applications through a [JSON-RPC](https://en.wikipedia.org/wiki/JSON-RPC) API.
|
|
This Howto shows how to use it and provides information about available functions.
|
|
|
|
See also
|
|
* wiki [rpcd](https://openwrt.org/docs/techref/rpcd)
|
|
* wiki [ubus](https://openwrt.org/docs/techref/ubus)
|
|
|
|
## Basics
|
|
The API is installed by default.
|
|
|
|
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.
|
|
The LuCI JSON-RPC server offers several independent APIs.
|
|
Therefore you have to use **different URLs for every exported library**.
|
|
Assuming your LuCI-Installation can be reached through `/cgi-bin/luci`, any exported library can be reached via `/cgi-bin/luci/rpc/LIBRARY`.
|
|
|
|
|
|
## Authentication
|
|
Most exported libraries will require a valid authentication to be called with.
|
|
If you get an `HTTP 403 Forbidden` status code you are probably missing a valid authentication token.
|
|
To get such a token you have to call the `login` method of the RPC-Library `auth`.
|
|
Following our example from above this login function would be provided at `/cgi-bin/luci/rpc/auth`.
|
|
The function accepts 2 parameters: `username` and `password` (of a valid user account on the host system) and returns an authentication token.
|
|
|
|
Example:
|
|
```sh
|
|
curl http://<hostname>/cgi-bin/luci/rpc/auth --data '
|
|
{
|
|
"id": 1,
|
|
"method": "login",
|
|
"params": [
|
|
"youruser",
|
|
"somepassword"
|
|
]
|
|
}'
|
|
```
|
|
|
|
response:
|
|
```json
|
|
{"id":1,"result":"65e60c5a93b2f2c05e61681bf5e94b49","error":null}
|
|
```
|
|
|
|
If you want to call any exported library which requires an authentication token you have to append it as a URL parameter auth to the RPC-Server URL.
|
|
E.g. instead of calling `/cgi-bin/luci/rpc/LIBRARY` you should call `/cgi-bin/luci/rpc/LIBRARY?auth=TOKEN`.
|
|
|
|
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.
|
|
|
|
|
|
## Exported Libraries
|
|
### uci
|
|
The UCI-Library `/rpc/uci` offers functionality to interact with the Universal Configuration Interface.
|
|
|
|
**Exported Functions:**
|
|
|
|
See [LuCI API](LuCI.uci.html)
|
|
|
|
Example:
|
|
```sh
|
|
curl http://<hostname>/cgi-bin/luci/rpc/uci?auth=yourtoken --data '
|
|
{
|
|
"method": "get_all",
|
|
"params": [ "network" ]
|
|
}'
|
|
```
|
|
|
|
### fs
|
|
The Filesystem library `/rpc/fs` offers functionality to interact with the filesystem on the host machine.
|
|
|
|
**Exported Functions:**
|
|
|
|
See [fs API](LuCI.fs.html)
|
|
|
|
|
|
**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.
|
|
|
|
|