Articles

Device APIs: what a modelled interface makes possible

A declared schema and a screen of text are different promises to the caller.

Reading: 5 minNetworking

Article cover: Device APIs: what a modelled interface makes possible

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 a Capabilities RPC, 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.txt lines 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.
Nodrius Field Kit — cover

Get the Nodrius Field Kit

Enter your email and we'll send you the complete Field Kit: eight technical resources in one download.

Your email address is sent to Nodrius and used to deliver the Field Kit to you by email. Marketing messages are separate and optional: the checkbox does not affect your download, and you are only added to our updates list if you tick it. Privacy Policy.

Privacy & cookies

This site does not use cookies, analytics or tracking, and it does not profile you. There is nothing technical to switch off, so Accept and Reject change nothing about how the site works: either choice lets you browse everything normally.

The only difference is what your browser remembers: two entries in local storage — your choice here, so this notice is not shown again, and a marker that the Field Kit offer has already been made — so the offer is presented once and not on every page. They contain no identifier, they are not shared with anyone, and the site sets no cookie for either.

What we do with your data
How your email address is used when you ask for a Resource, how long it is kept and which rights you have — in the Privacy Policy.
What the site stores in your browser
Two entries in local storage — your choice on this notice and whether the Field Kit offer has been shown — and no cookies, no session storage, no third-party content: in the Cookie Policy.