clnrest-register-path -- Command to add a path to clnrest

SYNOPSIS

clnrest-register-path path rpc_method [http_method] [rune_required] [rune_restrictions]

DESCRIPTION

Command added in v26.04.

clnrest-register-path is a low-level rpc command for plugin developers to register a custom REST API path with an associated RPC method and optional rune validation.

• path (string): The REST API path to register (e.g., '/v1/custom/endpoint'). Captures which translate to an rpc parameter of 'key:value' are written like this: '/user/{key}'
• rpc_method (string): The RPC method name to invoke when this path and http\_method combination is accessed.
• http_method (string, optional): HTTP method for this path. Valid values are: GET, POST, PUT, PATCH or DELETE. Defaults to POST.
• rune_required (boolean, optional): Whether a rune is required to access this path. Is only allowed to be false for GET requests. Defaults to true
• rune_restrictions (object, optional): Optional rune validation parameters to check before allowing access. These are passed to the checkrune RPC command. Omitting the rune_restrictions parameter means using your matched rpc method and the rpc params used. You can use this for example to not require the user to create a new rune for your rpc_method but rather require something like method=pay.:
  • nodeid (string, optional): Node id of requesting node (required until v23.11).
  • method (string, optional): Method for which rune needs to be validated (required until v23.11). Omitting this means your rpc_method will be used.
  • params (object, optional): Parameters for method. Omitting this means the rpc params from the request will be used.:

RETURN VALUE

On success, an empty object is returned.

ERRORS

The following errors may be reported:

• 32700: Message either indicating conflicting paths or invalid/missing parameters.

AUTHOR

daywalker90 is mainly responsible for this command.

SEE ALSO

lightning-createrune(7), lightning-checkrune(7)

EXAMPLES

Example 1:

Request:

lightning-cli clnrest-register-path -k "path"="/custom/endpoint/{user}" "rpc_method"="custom-rpc-method" "http_method"="GET" "rune_required"=False

{
  "id": "example:clnrest-register-path#1",
  "method": "clnrest-register-path",
  "params": {
    "path": "/custom/endpoint/{user}",
    "rpc_method": "custom-rpc-method",
    "http_method": "GET",
    "rune_required": false
  }
}

Response:

{}

Example 2:

Request:

lightning-cli clnrest-register-path -k "path"="/v1/superpay" "rpc_method"="superpay" "http_method"="POST" "rune_required"=True "rune_restrictions"='{"method": "pay"}'

{
  "id": "example:clnrest-register-path#2",
  "method": "clnrest-register-path",
  "params": {
    "path": "/v1/superpay",
    "rpc_method": "superpay",
    "http_method": "POST",
    "rune_required": true,
    "rune_restrictions": {
      "method": "pay"
    }
  }
}

Response:

{}