skip to content

How does a client invoke a YANG rpc or a YANG action over RESTCONF, compared with the same call over NETCONF?

level: middleimportance: nice to knowfreq 8%

answer

  1. operations that are not data edits
  2. POST, but to which URL?
  3. actions live on a data node
  4. an action element wrapping the path

basics

~20 s

RESTCONF invokes an rpc with POST to {+restconf}/operations/module:name, and an action with POST to its data node's URL plus the action name. NETCONF puts the rpc element inside <rpc>, or an <action> element carrying the node's full path and keys.

solid answer

~40 s

YANG defines operations two ways: a top-level `rpc` and, since YANG 1.1, an `action` bound to a data node. In RESTCONF both are `POST` requests: an rpc goes to `{+restconf}/operations/<module>:<name>`, an action to `{+restconf}/data/<path-to-node>/<action>`, with input in an `input` body. A success with no output returns `204 No Content`; with output, `200 OK` and an `output` body. In NETCONF an rpc's element sits directly inside `<rpc>`; an action is wrapped in `<action xmlns="urn:ietf:params:xml:ns:yang:1">` containing every container and list from the top down, list keys included, and the reply is `<ok/>` or the output elements. Only rpcs are listed under `{+restconf}/operations`, and NETCONF allows one action per `<rpc>`.

code

http · 7 lines
http
POST /restconf/data/example-actions:interfaces/interface=eth0/reset HTTP/1.1
Host: example.com
Content-Type: application/yang-data+json

{ "example-actions:input" : { "delay" : 600 } }

HTTP/1.1 204 No Content

go deeper

for a junior

Remember that both protocols invoke operations, and that in RESTCONF it is always a POST: to /operations for an rpc, to the data node's URL for an action.

for a middle

Explain how each protocol names the target node, a URL path with keys after the equals sign versus nested elements with keys, and how a reply without output looks in each.

for a senior

Point out the practical traps: actions missing from the operations listing, one action per NETCONF message, and invocations sitting outside any commit or rollback.

for a principal

Weigh where operational actions belong in an automation design, and how a stateless invoker reports and verifies results a later step depends on.

## Two kinds of YANG operation Most management traffic reads or edits data. Some work is neither: rebooting a device, resetting an interface, clearing counters, fetching a computed result. YANG models these as operations with optional `input` and `output` parameters: - an **`rpc`** statement defines a top-level operation of a module, such as `reboot`; - an **`action`** statement (YANG 1.1, RFC 7950 §7.15) defines an operation **bound to a data node**, such as `reset` on one entry of an interface list. The node it is called on is part of the call. Both protocols can invoke both, but they address them very differently. The examples below use the `example-actions` module from RFC 8040: a `reset` action, with a `delay` input in seconds, on each entry of the `interfaces/interface` list keyed by `name`. ## RESTCONF: POST to an operation resource RFC 8040 §3.6 calls each invocable operation an **operation resource**, always invoked with `POST`: | Operation | URL | |---|---| | rpc | `{+restconf}/operations/<module>:<rpc-name>` | | action | `{+restconf}/data/<path-to-data-node>/<action-name>` | `{+restconf}` is the API root the server advertises. For the reset action on `eth0` the path is `/restconf/data/example-actions:interfaces/interface=eth0/reset`; the list key travels in the URL after `=`. The body, if there is one, is the operation's input, encoded in the module's namespace as `input`: `{"example-actions:input": {"delay": 600}}` in JSON, or an `<input>` element in XML. Responses follow RFC 8040 §4.4.2 and §3.6: 1. Success and the operation defines no output: **`204 No Content`**, no body. 2. Success with output: **`200 OK`**, with an `output` object or element in the module namespace. 3. Not authorised: `403 Forbidden` with error-tag `access-denied` (a server may answer `404 Not Found` instead). Two details are easy to get wrong: - The `{+restconf}/operations` resource **lists rpcs only**. Actions are not listed there, "since they are invoked using a URI within the `{+restconf}/data` subtree" (§3.6). A client learns which actions exist from the YANG modules the server implements. - Among the per-datastore resources RFC 8527 adds for the NMDA, actions can be invoked only under `{+restconf}/ds/ietf-datastores:operational`. ## NETCONF: an element inside rpc NETCONF has one envelope for everything: `<rpc message-id="...">`, answered by `<rpc-reply>` with the same `message-id`. - A **data-model rpc** is sent as its own element, in its module's namespace, directly inside `<rpc>`, the same way the protocol's own operations such as `<get-config>` are sent. Input parameters are child elements. - An **action** is sent as an `<action>` element in the namespace `urn:ietf:params:xml:ns:yang:1` (RFC 7950 §7.15.2). Inside it the client writes the data tree from the top down to the node the action is on: **every container and list on the path, with every list key**, then the action's element holding its input. Replies carry the same outcomes in XML: a single `<ok/>` when the operation succeeds with no output, otherwise the output parameters as children of `<rpc-reply>`; a failure returns `<rpc-error>`. RFC 7950 also limits batching: **only one action may appear in one `<rpc>`**; if there are more, the server MUST reply with error-tag `bad-element`. ## Side by side | | RESTCONF | NETCONF | |---|---|---| | How the target node is named | URL path, keys after `=` | nested XML elements, keys as child leaves | | Where rpcs are discovered | listed under `{+restconf}/operations` | module capabilities and the YANG library | | Where actions are discovered | YANG modules only | YANG modules only | | Success, no output | `204 No Content` | `<ok/>` | | Success with output | `200 OK` plus `output` | output elements in `<rpc-reply>` | | Calls per message | one per POST | one action per `<rpc>` | ## What this means in practice - An invocation is **not an edit operation** in either protocol: it is not staged in a candidate, not held for a commit and not undone by discarding changes. Its effect is whatever the operation itself defines. - Because RESTCONF has no session, an operation whose result matters to a later step must report it in its output or in state data the client reads back. - Where an operation and an edit must be ordered, a NETCONF client can sequence them inside one session, under a lock; a RESTCONF client sequences independent requests.

  • Why does a RESTCONF client not find actions under {+restconf}/operations?
    Because an action belongs to a data node instance and is invoked under `{+restconf}/data`, at the node's own URL. RFC 8040 §3.6 lists only rpc operations under `{+restconf}/operations`. A client learns which actions exist from the YANG modules the server reports in its YANG library.
  • Can one NETCONF message invoke several actions at once?
    No. RFC 7950 §7.15.2 allows only one action per `<rpc>`, and a server receiving more MUST reply with error-tag `bad-element`. RESTCONF has the same shape by construction: one POST invokes one operation. Invoking an action on many interfaces means many messages.

saying these in an interview costs you the question

  • RESTCONF actions are invoked under /operations, exactly like rpcs.
  • A successful RESTCONF operation with no output still returns 200 OK.
  • NETCONF cannot invoke YANG 1.1 actions, only top-level rpcs.
  • In a NETCONF action element the list keys on the path are optional.
  • Invoking an action is a configuration edit that must be committed.