[PATCH V3 uhttpd] ubus: add new RESTful API

[Andre Valentin]

Hi Rafał!

I'm experimenting again a bit with the new API. I subscribed to the hostapd events and saw that
after some time the connection is still up, but now new events come in.
How can I control timeout and make sure, that the subscription connections stays as long as
possible online?

Kind regards,

André

Am 14.09.20 um 17:15 schrieb Rafał Miłecki:
> From: Rafał Miłecki <rafal at milecki.pl>
> 
> 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 at milecki.pl>
> ---
> V2: Use "Authorization" with Bearer for rpcd session id / token
>     Treat missing session id as UH_UBUS_DEFAULT_SID
>     Fix "result" format (was: "result":{{"foo":"bar"}})
> V3: Treat /ubus/ requests as legacy ones for backward compatibility.
>     Previously there were causing 404 (only /ubus was accepted).
>     Support requests with search path (e.g. ?foo=bar) by ignoring it.
>     This may be used by some clients to avoid caching responses.
>     Rebase on the [PATCH uhttpd] ubus: fix blob_buf initialization

-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 4052 bytes
Desc: S/MIME Cryptographic Signature
URL: <http://lists.openwrt.org/pipermail/openwrt-devel/attachments/20200923/126a3dd0/attachment.p7s>