skip to content

What does the RESTCONF content query parameter select, and what does a GET return when the parameter is left out?

level: juniorimportance: should knowfreq 12%

answer

  1. the YANG config statement splits it
  2. three values, one default
  3. settings versus live counters
  4. list keys survive the state-only cut

basics

~20 s

RESTCONF's content parameter chooses which descendants a GET returns: config (configuration only), nonconfig (state only) or all. Left out, it defaults to all, so the reply mixes settings and live state. Every server must support it.

solid answer

~40 s

`content` splits a retrieval along the YANG `config` statement. `content=config` returns only configuration descendants, `content=nonconfig` returns only state such as `oper-status` and the interface counters, and `content=all` returns both — and `all` is what a GET gets when the parameter is absent. RFC 8040 §4.8.1 makes it mandatory to implement, unlike `depth` or `fields`, and allows it only on retrievals of datastore and data resources; on any other method or resource type the server answers `400 Bad Request`. With `nonconfig` the server still returns list keys and configuration ancestors, so every counter stays attached to the interface it belongs to. A dashboard that shows live state should send `content=nonconfig`; a configuration backup should send `content=config`.

go deeper

for a junior

Recall the three values — config, nonconfig, all — and that leaving the parameter out means all. Tie the split to YANG's config statement.

for a middle

Explain that a state-only reply still carries list keys and config ancestors, and that the parameter is mandatory to implement and only legal on retrievals.

for a senior

Show the operational habit: dashboards send nonconfig, backups send config, and neither relies on the default. Know that default-value reporting is a separate parameter.

for a principal

Frame it as API hygiene for automation at scale: callers declare which half of the tree they consume, which keeps replies small and makes intent visible in every request.

## What the parameter is for A **RESTCONF** server (RFC 8040) exposes a device's YANG-modelled data as HTTP resources under `{+restconf}/data`, the unified datastore resource. A plain `GET` on a container returns everything beneath it: the settings an operator wrote *and* the live state the device computed. On a core router those two halves are very different in size and in purpose. The **`content` query parameter** lets the client keep only one of them. ## Where the line between config and state comes from The split is not invented by RESTCONF. It comes from the YANG **`config` statement** (RFC 7950 §7.21.1): - `config true` marks **configuration** — data that belongs in configuration datastores and that a client may write. - `config false` marks **state data** (RFC 8040 also calls it non-configuration data) — counters, operational status, learned tables. - A node without the statement inherits its parent's value; a top-level node defaults to `true`. - Nothing beneath a `config false` node can be `config true`. In the `ietf-interfaces` module (RFC 8343), `name`, `description` and `enabled` are configuration, while `oper-status`, `speed` and the whole `statistics` container (`in-octets`, `out-octets` and the rest) are state. ## The three values | Value | Returns | Typical caller | |---|---|---| | `config` | only configuration descendants | a backup or drift-detection job | | `nonconfig` | only non-configuration descendants | a dashboard, a poller, a troubleshooting script | | `all` | every descendant | a human exploring the tree; also the **default** | If the parameter is absent the server behaves exactly as for `content=all`. That default is why a naive dashboard that only wants counters still receives every description, every enabled flag and every other setting on the path. ## What survives a state-only cut A state-only reply would be useless if it dropped the information needed to tell entries apart. RFC 8040's own example (Appendix B.3.1) notes that with `content=nonconfig` the server also returns **configuration ancestors and list key leafs**. So a request for the interface list with `content=nonconfig` still carries each entry's `name`: ```json { "ietf-interfaces:interfaces": { "interface": [ { "name": "eth0", "oper-status": "up", "statistics": { "in-octets": "918273645512" } } ] } } ``` (Abridged. `in-octets` is a `counter64`, a `uint64`, which the JSON encoding of RFC 7951 writes as a string.) ## Rules a client can rely on 1. **Mandatory.** RFC 8040 §4.8.1 says `content` MUST be supported. It has no capability URI, because only optional parameters are advertised (§9.1.1 lists `depth`, `fields`, `filter`, `replay` and `with-defaults`). 2. **Retrieval only.** It is allowed on `GET` for datastore and data resources; on another method or resource type the server returns `400 Bad Request`. It cannot limit what a `PUT` replaces. 3. **Exact spelling.** Query parameter names and values are case sensitive, and a parameter may appear at most once — a repeated parameter draws `400 Bad Request` with error-tag `invalid-value` (§4.8). 4. **Composable.** It can be combined with the other retrieval parameters, such as `depth` and `fields`, in one request. ## What content is not The parameter is often confused with neighbouring mechanisms: - **Not a datastore selector.** `{+restconf}/data` is one unified view of the device. Choosing among the NMDA datastores, such as running or operational, is done by the separate `/ds/` resources of RFC 8527, not by `content`. - **Not a default-value switch.** Whether leaves that hold their YANG default appear in the reply is decided by the server's advertised basic-mode and the separate `with-defaults` parameter. - **Not an edit scope.** A `PUT` replaces and a plain `PATCH` merges whatever the body says; `content` on either draws `400 Bad Request`. - **Not a name filter.** It halves the tree; picking individual nodes by name is what `fields` does. ## Using it well - A monitoring poller that only displays state should send `content=nonconfig`; it shrinks the reply by everything the operator configured and makes it obvious, when reading the code, that the caller never looks at settings. - A configuration backup should send `content=config`. The state would otherwise churn on every run — counters move every second — and turn every diff into noise. - `content` is coarse: it cuts the tree in two, not down to one leaf. To fetch one counter from every interface, combine it with a name-based selection (`fields`) or address the leaf directly. The point to carry into an interview: the default is `all`, the split follows the YANG `config` statement, the parameter is mandatory for every server, and a state-only reply keeps the keys that make it readable.

  • Which YANG rule decides whether a node without its own config statement counts as configuration?
    It inherits its parent's `config` value; a top-level node without the statement defaults to `true` (RFC 7950 §7.21.1). Once a node is `config false`, nothing beneath it may be `config true`, so a whole `statistics` container marked `config false` is state all the way down and disappears entirely from a `content=config` reply.
  • What does a RESTCONF server do with a request that carries content twice, or spells it Content?
    RFC 8040 §4.8 allows each query parameter at most once; a repeated one draws `400 Bad Request` with error-tag `invalid-value`. Names and values are case sensitive, so `Content` is not the `content` parameter at all — it is an unexpected parameter, which also draws `400 Bad Request` with `invalid-value`.

saying these in an interview costs you the question

  • The default is config, so state never appears unless asked for.
  • content is optional, so check the capability list before using it.
  • content=nonconfig strips list keys, so counters arrive unlabelled.
  • content can limit which descendants a PUT replaces.
  • content controls whether default-valued leaves are reported.