ubus: add new RESTful API
authorRafał Miłecki <rafal@milecki.pl>
Mon, 14 Sep 2020 15:15:23 +0000 (17:15 +0200)
committerRafał Miłecki <rafal@milecki.pl>
Tue, 15 Sep 2020 11:22:48 +0000 (13:22 +0200)
commit11723570af9cb7bd87842e79c85ee99530be9902
tree32b8f70cea60a84f1b010787894a5f75e035e0b5
parentfe1888f19e7f8ee4237409b8616c82926190c2f8
ubus: add new RESTful API

Initial uhttpd ubus API was fully based on JSON-RPC. That restricted it
from supporting ubus notifications that don't fit its model.

Notifications require protocol that allows server to send data without
being polled. There are two candidates for that:
1. Server-sent events
2. WebSocket

The later one is overcomplex for this simple task so ideally uhttps ubus
should support text-based server-sent events. It's not possible with
JSON-RPC without violating it. Specification requires server to reply
with Response object. Replying with text/event-stream is not allowed.

All above led to designing new API that:
1. Uses GET and POST requests
2. Makes use of RESTful URLs
3. Uses JSON-RPC in cleaner form and only for calling ubus methods

This new API allows:
1. Listing all ubus objects and their methods using GET <prefix>/list
2. Listing object methods using GET <prefix>/list/<path>
3. Listening to object notifications with GET <prefix>/subscribe/<path>
4. Calling ubus methods using POST <prefix>/call/<path>

JSON-RPC custom protocol was also simplified to:
1. Use "method" member for ubus object method name
   It was possible thanks to using RESTful URLs. Previously "method"
   had to be "list" or "call".
2. Reply with Error object on ubus method call error
   This simplified "result" member format as it doesn't need to contain
   ubus result code anymore.

This patch doesn't break or change the old API. The biggest downside of
the new API is no support for batch requests. It's cost of using RESTful
URLs. It should not matter much as uhttpd supports keep alive.

Example usages:

1. Getting all objects and their methods:
$ curl http://192.168.1.1/ubus/list
{
"dhcp": {
"ipv4leases": {

},
"ipv6leases": {

}
},
"log": {
"read": {
"lines": "number",
"stream": "boolean",
"oneshot": "boolean"
},
"write": {
"event": "string"
}
}
}

2. Getting object methods:
$ curl http://192.168.1.1/ubus/list/log
{
"read": {
"lines": "number",
"stream": "boolean",
"oneshot": "boolean"
},
"write": {
"event": "string"
}
}

3. Subscribing to notifications:
$ curl http://192.168.1.1/ubus/subscribe/foo
event: status
data: {"count":5}

4. Calling ubus object method:
$ curl -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "login",
    "params": {"username": "root", "password": "password" }
}' http://192.168.1.1/ubus/call/session
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"ubus_rpc_session": "01234567890123456789012345678901",
(...)
}
}

$ curl -H 'Authorization: Bearer 01234567890123456789012345678901' -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "write",
    "params": {"event": "Hello world" }
}' http://192.168.1.1/ubus/call/log
{
"jsonrpc": "2.0",
"id": 1,
"result": null
}

Signed-off-by: Rafał Miłecki <rafal@milecki.pl>
main.c
ubus.c
uhttpd.h