skip to content

Datastores and Root Resources

3 roadmaps4 questions

RESTCONF edits one unified datastore under /data and runs RPCs under /operations, and needs the NMDA /ds resources to reach running or operational directly. Candidate-style workflows surprise people.

on this pageshow

explore

questions

4

In RESTCONF, what does each child of the API root resource — data, operations and yang-library-version — give a client?

level: juniorimportance: must knowfreq 16%

answer

  1. three children, two mandatory
  2. config and state in one tree
  3. RPCs as empty leaves
  4. a revision date, not a protocol version

basics

~20 s

Under the RESTCONF API root, data is the one combined datastore of configuration and state that clients read and edit, operations lists and invokes the server's YANG RPCs, and yang-library-version gives the ietf-yang-library revision the server implements.

solid answer

~40 s

The API root, written `{+restconf}` because its path is discovered rather than fixed, defines three children. `{+restconf}/data` is mandatory: one conceptual datastore holding configuration and state together, read with GET and edited with POST, PUT, PATCH and DELETE on what it contains; the client can neither create nor delete it. `{+restconf}/operations` is optional and lists each data-model RPC as an empty leaf, invoked with `POST {+restconf}/operations/<module>:<rpc>`; YANG actions are absent because they are invoked on their data node under `/data`. `{+restconf}/yang-library-version` is a mandatory read-only leaf holding the revision date of `ietf-yang-library`, which tells the client which module list to read before it builds any URL. A GET on the root returns all three as `ietf-restconf:restconf`.

code

http · 14 lines
http
GET /mgmt/restconf HTTP/1.1
Host: router1.example.net
Accept: application/yang-data+json

HTTP/1.1 200 OK
Content-Type: application/yang-data+json

{
  "ietf-restconf:restconf" : {
    "data" : {},
    "operations" : {},
    "yang-library-version" : "2019-01-04"
  }
}

go deeper

for a junior

Name the three children of the RESTCONF root and say in one line what each is for; know that /data mixes configuration and state.

for a middle

Explain why RPCs sit under /operations while actions are invoked on their data node, and what the client does with the yang-library-version value.

for a senior

Point out what the root does not offer — individual datastores, capabilities, links — and where a client finds each of them instead.

for a principal

Weigh RESTCONF's schema-driven, link-free design: clients must load the YANG library first, which ties automation tooling to the device's module set.

## The API root **RESTCONF** (RFC 8040) is an HTTPS interface to data modelled in **YANG**, the IETF's data modelling language for network configuration and state. Every RESTCONF request starts from one **API root**. The RFC writes it as the URI template `{+restconf}` because its path is not fixed: the server announces it through `/.well-known/host-meta`, and `/restconf` is only the path the RFC's own examples use. A GET on the root returns the **API resource** itself, named `ietf-restconf:restconf` in JSON. Its structure comes from the `yang-api` data template in the `ietf-restconf` module, which defines three children: two mandatory, one optional. | Child | Required? | What it holds | Methods a client uses | |---|---|---|---| | `data` | mandatory | the datastore resource: all configuration and state data | GET and HEAD to read; POST, PUT, PATCH, DELETE to edit what is inside | | `operations` | optional — omitted when the server advertises no data-model RPCs | one empty leaf per RPC operation | GET to list, POST to invoke | | `yang-library-version` | mandatory, read-only | the revision date of `ietf-yang-library` | GET | ## `{+restconf}/data` — one datastore, two kinds of data - **A combined view.** RFC 8040 section 3.3.1 describes it as the combined configuration and state data resources a client can access. **Configuration** nodes (`config true`) and **state** nodes (`config false`) sit in one tree; which is which comes from the YANG `config` statement, not from the URL. - **No choice of datastore.** RESTCONF was designed as a subset of NETCONF that eliminates datastores and explicit locking (section 1.2). There is no `/data/running` or `/data/candidate`; the server decides which underlying datastore an edit lands in, and each edit takes effect when it completes. - **The client cannot create or delete it.** It can read it (the reply is a node named `data` in the `ietf-restconf` namespace), create a top-level node inside it with POST, and replace its entire contents with a PUT on `/data` itself — RFC 8040's counterpart of NETCONF `<copy-config>`. - **Top-level paths are module-qualified**, for example `{+restconf}/data/ietf-interfaces:interfaces`. How deeper nodes and list keys are spelt in the path is a separate subject, the URL mapping of YANG schema nodes. ## `{+restconf}/operations` — the RPC catalogue Each YANG `rpc` statement in a module the server advertises becomes an **operation resource** here. A GET on `/operations` lists them, each represented as an empty leaf (`[null]` in JSON). A POST to `{+restconf}/operations/<module>:<rpc>` invokes one, with the RPC's `input` as the body; success returns `200 OK` with a body when the RPC has output, and `204 No Content` when it has none. Two things are deliberately not listed there: 1. **YANG actions.** An action is bound to a data node, so it is invoked with POST on that node's path under `{+restconf}/data`, followed by the action's name. 2. **The edit and retrieval verbs themselves.** HTTP methods stand in for NETCONF's `<get>`, `<get-config>`, `<edit-config>` and `<copy-config>`, so they are not RPCs a client looks up. ## `{+restconf}/yang-library-version` — which module list to read RESTCONF has no discovery of data resources (section 3): the client derives every URL from the YANG modules the server advertises, and those are listed by the `ietf-yang-library` module, which the server MUST implement. The `yang-library-version` leaf holds that module's revision date in `YYYY-MM-DD` form, so the client knows which layout to read before it asks: - The revision published in RFC 7895, which RFC 8040's examples show as `2016-06-21`, lists modules under `{+restconf}/data/ietf-yang-library:modules-state`. - RFC 8525, which obsoletes RFC 7895, carries revision `2019-01-04`. It adds a datastore-aware `yang-library` tree for the Network Management Datastore Architecture (NMDA) and marks `modules-state` deprecated, which an NMDA server SHOULD still populate for older clients. The leaf therefore reports a **library revision**, not the RESTCONF protocol version and not the YANG language version. ## What the root does not give you - **A list of datastores.** `/data` is a single view; reaching `running`, `intended` or `operational` individually needs the NMDA resources RFC 8527 adds under `{+restconf}/ds`. - **Protocol capabilities.** Optional features such as query parameters are advertised in the `ietf-restconf-monitoring` module, read at `{+restconf}/data/ietf-restconf-monitoring:restconf-state/capabilities`. - **Links to children.** RFC 8040 section 1.3 rejects hypermedia links in responses because the YANG modules already tell the client every path. ## Common misreadings - "The root is `/restconf`." It is wherever host-meta says. - "`/data` is the running datastore." It is a combined view of configuration and state. - "Actions live under `/operations`." Only RPCs do.

  • Why do RESTCONF responses carry no hypermedia links from /data to its children?
    RFC 8040 section 1.3 makes RESTCONF schema-driven: knowing the YANG modules the server lists in `ietf-yang-library`, a client can derive every resource URL and message structure, so links in responses are unnecessary. Section 3 states there is no data resource discovery mechanism at all — the advertised modules are the map.
  • What status does a successful POST to /operations/<module>:<rpc> return?
    `200 OK` with a body carrying the RPC's output when there is a response body, and `204 No Content` with no body when the RPC has no output (RFC 8040 sections 3.6 and 4.4.2). An unauthorised caller SHOULD get `403 Forbidden` with error-tag `access-denied`.

saying these in an interview costs you the question

  • The RESTCONF root is always /restconf, so discovery is optional.
  • /data is the running datastore and holds only configuration.
  • YANG actions are listed and invoked under /operations like RPCs.
  • yang-library-version reports the RESTCONF protocol version.
  • A client can DELETE /data to wipe the device's configuration.
open as a page

A RESTCONF server shares a device with NETCONF offering :candidate but not :writable-running; what happens to the datastores when a RESTCONF PATCH to /data succeeds?

level: seniorimportance: must knowfreq 11%

basics

~20 s

The PATCH edits the candidate, and the RESTCONF server must commit the candidate to running immediately after the edit — taking any other client's uncommitted candidate edits live with it — and, if the device has :startup, also update startup.

open as a page

A RESTCONF client hard-codes /restconf and gets 404 from a device whose API lives elsewhere; how should it find the API root?

level: middleimportance: should knowfreq 11%

basics

~10 s

A RESTCONF client must not assume /restconf: it sends GET /.well-known/host-meta, takes the single Link whose rel is restconf from the XRD reply, and prefixes that href to every later request, such as href/data.

open as a page

On an NMDA RESTCONF server, why read /ds/ietf-datastores:operational instead of /data to check whether a configured interface setting is actually in use?

level: seniorimportance: should knowfreq 7%

basics

~10 s

RESTCONF's /data is RFC 8040's combined view, whose configuration nodes show what was configured; RFC 8527's /ds/ietf-datastores:operational returns only values the system is actually using, and with-origin can say where each came from.

open as a page