LIGHTNING-CLNREST-REGISTER-PATH(7)

📦
version 26.06.9 · 2 versions
, in nixpkgs unstable

✨ LIGHTNING-CLNREST-REGISTER-PATH ✨

okay bestie, so this is the lightning-clnrest-register-path manual page (section 7 of the manuals, iykyk) and it's genuinely such a vibe — it's the little command that lets your plugin slide a whole custom REST endpoint into clnrest. let's get into it 💅

🌸 NAME 🌸

clnrest-register-path — the command that adds a path to clnrest 🎀

🦋 SYNOPSIS 🦋

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

💖 DESCRIPTION 💖

so this command is new new, like, it was added in v26.04 ⭐

clnrest-register-path is a low-level rpc command for plugin developers — yes, that's you, main character — and what it does is register a custom REST API path with an associated RPC method, plus optional rune validation. it's giving "let me build my own door into the house" 🚪✨

here's the whole cast of parameters:

  • path (string): the REST API path you wanna register (like, for example, '/v1/custom/endpoint'). and the captures that translate into an rpc parameter of 'key:value' get written like this: '/user/{key}' 👑
  • rpc_method (string): the RPC method name that gets invoked when this path + http_method combo gets accessed.
  • http_method (string, optional): the HTTP method for this path. valid values are: GET, POST, PUT, PATCH or DELETE. defaults to POST. no cap.
  • rune_required (boolean, optional): whether a rune is required to access this path. it's only allowed to be false for GET requests — literally only GET, don't try it. defaults to true.
  • rune_restrictions (object, optional): optional rune validation parameters to check before allowing access. these get 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 the 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 you get an empty object back. that's it. {} and you're slaying 💀✨

😭 ERRORS 😭

here's what can go wrong, bestie — the following errors may be reported:

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

👑 AUTHOR 👑

daywalker90 is mainly responsible for this command. thank you daywalker90, icon behaviour fr fr 🫡💜

🌈 SEE ALSO 🌈

🍓 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:

{}

and that's the whole page, bestie — brought to you by Core Lightning v26.06.9, the LIGHTNING-CLNREST-REGISTER-PATH(7) manual, and me, your resident unix girly. now go register a path and make it iconic 💅✨🎀

📦 where this page comes from