mirror of
https://github.com/ElementsProject/lightning.git
synced 2025-02-21 22:31:48 +01:00
doc: update clnrest documentation.
This commit is contained in:
Tony Aldon
ShahanaFarooqui
parent
baa9a96eb1
commit
8a62831847
2 changed files with 39 additions and 16 deletions
|
|
@ -3,15 +3,16 @@ title: "REST APIs"
|
|||
slug: "rest"
|
||||
hidden: false
|
||||
createdAt: "2023-09-05T09:54:01.784Z"
|
||||
updatedAt: "2023-09-05T09:54:01.784Z"
|
||||
updatedAt: "2023-10-13T09:54:01.784Z"
|
||||
---
|
||||
|
||||
# CLNRest
|
||||
|
||||
CLNRest is a lightweight Python-based core lightning plugin that transforms RPC calls into a REST service. By generating REST API endpoints, it enables the execution of Core Lightning's RPC methods behind the scenes and provides responses in JSON format.
|
||||
|
||||
A complete documentation for the REST interface is available at [REST API REFERENCE](ref:get_list_methods_resource).
|
||||
CLNRest is a lightweight Python-based built-in Core Lightning plugin (from v23.08) that transforms RPC calls into a REST service.
|
||||
It also broadcasts Core Lightning notifications to listeners connected to its websocket server. By generating REST API endpoints,
|
||||
it enables the execution of Core Lightning's RPC methods behind the scenes and provides responses in JSON format.
|
||||
|
||||
An online demo for the REST interface is available at [REST API REFERENCE](ref:get_list_methods_resource).
|
||||
|
||||
> 📘 Pro-tip
|
||||
>
|
||||
|
|
@ -34,22 +35,34 @@ A complete documentation for the REST interface is available at [REST API REFERE
|
|||
|
||||
## Installation
|
||||
|
||||
Install required packages with `pip install json5 flask flask_restx gunicorn pyln-client flask-socketio gevent gevent-websocket` or `pip install -r requirements.txt`.
|
||||
The plugin is built-in with Core Lightning but its python dependencies are not, and must be installed separately.
|
||||
Install required packages with `pip install -r plugins/clnrest/requirements.txt`.
|
||||
|
||||
Note: if you have the older c-lightning-rest plugin, you can configure Core Lightning with `disable-plugin=clnrest.py` option
|
||||
to avoid any conflict with this one. Of course, you could use this one instead!
|
||||
|
||||
Note: if you have the older c-lightning-rest plugin, you can use `disable-plugin clnrest.py` to avoid any conflict with this one. Of course, you could use this one instead!
|
||||
|
||||
## Configuration
|
||||
|
||||
If `rest-port` is not specified, the plugin will disable itself.
|
||||
|
||||
- --rest-port: Sets the REST server port to listen to (3010 is common)
|
||||
|
||||
- --rest-protocol: Specifies the REST server protocol. Default is HTTPS.
|
||||
|
||||
- --rest-host: Defines the REST server host. Default is 127.0.0.1.
|
||||
- --rest-certs: Defines the path for HTTPS cert & key. Default path is same as RPC file path to utilize gRPC's client certificate. If it is missing at the configured location, new identity will be generated.
|
||||
|
||||
- --rest-certs: Defines the path for HTTPS cert & key. Default path is same as RPC file path to utilize gRPC's client certificate.
|
||||
If it is missing at the configured location, new identity will be generated.
|
||||
|
||||
- --rest-csp: Creates a whitelist of trusted content sources that can run on a webpage and helps mitigate the risk of attacks.
|
||||
Default CSP is set as `default-src 'self'; font-src 'self'; img-src 'self' data:; frame-src 'self'; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline';`.
|
||||
Example CSP: `rest-csp=default-src 'self'; font-src 'self'; img-src 'self'; frame-src 'self'; style-src 'self'; script-src 'self';`.
|
||||
- --rest-cors-origins: Define multiple origins which are allowed to share resources on web pages to a domain different from the one that served the web page. Default is `*` which allows all origins. Example to define multiple origins:
|
||||
Default CSP:
|
||||
`default-src 'self'; font-src 'self'; img-src 'self' data:; frame-src 'self'; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline';`
|
||||
Example CSP:
|
||||
`rest-csp=default-src 'self'; font-src 'self'; img-src 'self'; frame-src 'self'; style-src 'self'; script-src 'self';`.
|
||||
|
||||
- --rest-cors-origins: Define multiple origins which are allowed to share resources on web pages to a domain different from the
|
||||
one that served the web page. Default is `*` which allows all origins. Example to define multiple origins:
|
||||
|
||||
```
|
||||
rest-cors-origins=https://localhost:5500
|
||||
|
|
@ -60,21 +73,31 @@ rest-cors-origins=https?://127.0.0.1:([0-9]{1,4}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65
|
|||
|
||||
## Server
|
||||
|
||||
With the default configurations, the Swagger user interface will be available at https://127.0.0.1:3010/. The POST method requires `rune` header for authorization.
|
||||
With the default configurations, the Swagger user interface will be available at https://127.0.0.1:3010/.
|
||||
The POST method requires `rune` header for authorization.
|
||||
|
||||
- A new `rune` can be created via [createrune](https://docs.corelightning.org/reference/lightning-createrune) or the list of existing runes can be retrieved with [listrunes](https://docs.corelightning.org/reference/lightning-listrunes) command.
|
||||
- A new `rune` can be created via [createrune](https://docs.corelightning.org/reference/lightning-createrune) or the list of
|
||||
existing runes can be retrieved with [listrunes](https://docs.corelightning.org/reference/lightning-listrunes) command.
|
||||
|
||||
Note: in version v23.08, a parameter `Nodeid` was required to be the id of the node we're talking to (see `id (pubkey)` received from [getinfo](https://docs.corelightning.org/reference/lightning-getinfo) ). You can still send this for backwards compatiblity, but it is completely ignored.
|
||||
Note: in version v23.08, a parameter `Nodeid` was required to be the id of the node we're talking to (see `id (pubkey)` received
|
||||
from [getinfo](https://docs.corelightning.org/reference/lightning-getinfo)). You can still send this for backwards compatiblity,
|
||||
but it is completely ignored.
|
||||
|
||||
### cURL
|
||||
Example curl command for POST will also require a `rune` header like below:
|
||||
`curl -k -X POST 'https://127.0.0.1:3010/v1/getinfo' -H 'Rune: <node-rune>'`
|
||||
`curl -k -X POST 'https://localhost:3010/v1/getinfo' -H 'Rune: <node-rune>'`
|
||||
|
||||
With `-k` or `--insecure` option curl proceeds with the connection even if the SSL certificate cannot be verified.
|
||||
This option should be used only when testing with self signed certificate.
|
||||
|
||||
## Websocket Server
|
||||
Websocket server is available at `https://127.0.0.1:3010`. clnrest queues up notifications received for a second then broadcasts them to listeners.
|
||||
Websocket server is available at `https://127.0.0.1:3010`. clnrest queues up notifications received for a second
|
||||
then broadcasts them to all listeners.
|
||||
|
||||
This websocket server requires a `rune` with at least `readonly` access for authorization. The default method used
|
||||
for current validation is `listclnrest-notifications`. User can either provided a rune with minimum `readonly`
|
||||
access or can create a new special purpose rune, only for websocket validation, with restrictions='[["method=listclnrest-notifications"]]'.
|
||||
The client will only receive notifications if `rune`, provided in headers, allows it.
|
||||
|
||||
### Websocket client examples
|
||||
|
||||
|
|
|
|||
|
|
@ -27,7 +27,7 @@ You will need some Python packages if you want to use clnrest. Unfortunately th
|
|||
|
||||
```
|
||||
sudo apt-get install python3-json5 python3-flask python3-gunicorn
|
||||
pip3 install --user flask_restx pyln-client
|
||||
pip3 install --user flask-cors flask_restx pyln-client flask-socketio gevent gevent-websocket
|
||||
```
|
||||
|
||||
If you're on a different distribution or OS, you can compile the source by following the instructions from [Installing from Source](<>).
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue