Device APIs: what a modelled interface makes possible
A declared schema and a screen of text are different promises to the caller.

Every device interface answers one question before anything is typed: must the caller interpret what the device produced, or was the data declared in advance? A CLI returns text a person reads or guesses at; a model-driven interface returns data shaped by a schema both sides hold — YANG — carried by a protocol (NETCONF, RESTCONF or gNMI) in an encoding (XML or JSON) chosen separately. That lets a change be staged and committed rather than typed into a live system.
From a screen to a model
A CLI fuses three things a modelled interface keeps apart: the model (the schema — which nodes exist, how they nest, what each value may be), the protocol (how a client reads and changes them) and the encoding (how the values travel). Change the model and every holder must move together.
model YANG: modules -> containers -> leaves, each with a type
|
protocol NETCONF (over SSH) RESTCONF (over HTTP) gNMI (over gRPC)
|
encoding XML JSON (CLI text: none of this)
The model: YANG
A YANG module “defines hierarchies of schema nodes” and is “self-contained” and “compilable” (rfc7950.txt lines 764-766). A container groups child nodes; a leaf “has a value but no child nodes”. The result is a schema tree — “The definition hierarchy specified within a module” (line 794) — against which a data tree of real instances is checked: the schema is the contract.
NETCONF: datastores and a commit
NETCONF runs over SSH as a subsystem named “netconf”, on IANA-assigned TCP port 830 (rfc6242.txt lines 136-137). A configuration datastore holds configuration, not state: the running datastore always exists, and the optional candidate is “used to hold configuration data that can be manipulated without impacting the device’s current configuration” (rfc6241.txt lines 2961-2962). Commit is transactional: “If the device is unable to commit all of the changes in the candidate configuration datastore, then the running configuration MUST remain unchanged” (lines 3036-3040).
RESTCONF: the same model over HTTP
RESTCONF keeps YANG and the datastore concepts but drops the ceremony: it is “a subset of the interaction capabilities provided by the NETCONF protocol – for instance, by eliminating datastores and explicit locking” (rfc8040.txt lines 592-594). Edits are the HTTP methods POST, PUT, PATCH and DELETE, each “activated upon successful completion of the edit”; with no candidate, the request is the change. Its gain is discoverability: given the YANG library, resource URLs follow from the schema (lines 626-629).
gNMI: one service for configuration and telemetry
gNMI is gRPC-based: “a single gRPC service definition can cover both configuration and telemetry” (gNMI specification, lines 89-90). Get returns a snapshot, Set changes state, Subscribe opens a stream. A SetRequest is one transaction — “either all modifications within the request are applied, or the target MUST rollback the state changes” (lines 1260-1262) — and its subscription modes are named: ONCE, POLL and STREAM. Sessions “MUST be encrypted using TLS” (line 973).
Encoding is a separate decision
The model does not fix the encoding: YANG data travels as XML or, per RFC 7951, as JSON, and the two are interchangeable only with the model in hand — “such conversions require the YANG data model to be available” (rfc7951.txt lines 211-214). RFC 7951 is stricter than plain JSON: YANG’s JSON form carries “partial type information (number, string, boolean)”. “A JSON API” is not the same claim as “a modelled API”; schema validation belongs to the Automation & AI area.
Access control at the interface
Authorization does not disappear; it becomes expressible as data. NETCONF and RESTCONF share the Network Configuration Access Control Model: users belong to groups, rule-lists match groups, and rules grant one of read, create, delete, update or execute on a path within a module (rfc8341.txt lines 291-292). When no rule matches, the request is “rejected with an "access-denied" error” (rfc8341.txt lines 916-917) — an explicit default-deny — and a model can mark sensitive subtrees with nacm:default-deny-write.
The consequences in operations
Three habits keep a client working.
- Discover, do not assume. All three advertise what they support — NETCONF in the
<hello>exchange, gNMI through aCapabilitiesRPC, RESTCONF through its YANG library — so a client that hard-codes a model version will meet a device without it. - Know what “absent” means. A read may omit a node sitting at its default value — a server is “allowed to exclude data nodes that it considers to contain the default value” (
rfc6243.txtlines 236-237) — so absent is not the same as off. - Separate configuration from state.
<running>,<startup>,<candidate>and<intended>are the conventional datastores;<operational>is “a read-only datastore” holding “system state and all configuration actually used by the system”.
Limits and the common errors
Treating “model-driven” as “already validated” is the first error: a schema guarantees shape, not truth, and a device’s model is the vendor’s, so where it deviates the client suffers. The second is assuming the interfaces are interchangeable — NETCONF has a candidate and a commit, RESTCONF does not, and gNMI’s transaction covers one request — so choosing one changes what a partial failure means. The third is retiring the CLI too early, because coverage is uneven. Rate limits and retries belong to the Automation & AI sheets.
Level and prerequisites
L5 — specialist. It assumes the L1 vocabulary (packet journey, ports, transport) and the L3 telemetry sheet for SNMP, and re-teaches neither. Sibling sheets take over from here: Python for collection and validation, Ansible for configuration, and the versioning, validation and drift sheets.
Where to go next
References
- RFC 6241 — Network Configuration Protocol (NETCONF) (Enns, Bjorklund, Schoenwaelder, Bierman, Eds., June 2011).
- RFC 6242 — Using the NETCONF Protocol over Secure Shell (SSH) (Wasserman, June 2011).
- RFC 6243 — With-defaults Capability for NETCONF (Bierman, Lengyel, June 2011).
- RFC 7950 — The YANG 1.1 Data Modeling Language (Bjorklund, Ed., August 2016).
- RFC 7951 — JSON Encoding of Data Modeled with YANG (Lhotka, August 2016).
- RFC 8040 — RESTCONF Protocol (Bierman, Bjorklund, Watsen, January 2017).
- RFC 8259 — The JavaScript Object Notation (JSON) Data Interchange Format (Bray, Ed., December 2017).
- RFC 8341 — Network Configuration Access Control Model (NACM) (Bierman, Bjorklund; STD 91, March 2018).
- RFC 8342 — Network Management Datastore Architecture (NMDA) (Bjorklund, Schoenwaelder, Shafer, Watsen, Wilton, March 2018).
- RFC 8526 — NETCONF Extensions to Support the Network Management Datastore Architecture (Bjorklund et al., March 2019).
- gNMI — gRPC Network Management Interface, version 0.10.0 (OpenConfig, 25 May 2023); a project specification, not a standard.