skip to content

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%

answer

  1. the path is the device's choice
  2. a well-known URI
  3. an XRD document with links
  4. one link relation named restconf

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.

solid answer

~40 s

RFC 8040 section 3.1 says that when first connecting, a client MUST determine the RESTCONF root, because deployments choose where the API lives. It does so with `GET /.well-known/host-meta` (the RFC 6415 well-known resource), reads the `<Link rel='restconf' href='...'/>` element from the XRD reply — the server MUST return exactly one `restconf` link relation, and any other relations are irrelevant — and then uses that href as the initial part of every request path: `{href}/data`, `{href}/operations`, `{href}/yang-library-version`. `/restconf` is only what the RFC's examples use. Because discovery is per endpoint, one host:port can carry only one RESTCONF server, and a later RESTCONF version is expected to use a different root found through a different link relation.

code

http · 14 lines
http
GET /.well-known/host-meta HTTP/1.1
Host: router1.example.net
Accept: application/xrd+xml

HTTP/1.1 200 OK
Content-Type: application/xrd+xml

<XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>
    <Link rel='restconf' href='/mgmt/restconf'/>
</XRD>

GET /mgmt/restconf/yang-library-version HTTP/1.1
Host: router1.example.net
Accept: application/yang-data+json

go deeper

for a junior

Remember that /restconf is only the example path and that the real root comes from GET /.well-known/host-meta.

for a middle

Walk through the exchange: XRD reply, the single rel='restconf' link, and its href prefixed to every later request.

for a senior

Diagnose 404s from hard-coded roots across a mixed fleet and explain the one-server-per-host:port consequence of the mechanism.

for a principal

Decide how fleet automation caches discovered roots and when it rediscovers, given that proxies and upgrades can move the API without notice.

## Why the root is not fixed **RESTCONF** (RFC 8040) maps YANG-modelled configuration and state onto HTTPS resources. Every resource hangs off one **API root**, written `{+restconf}` in the RFC. The RFC deliberately does not fix that path: following URI-design best practice, a deployment decides where the API lives. A device may share its web server with other applications, sit behind a reverse proxy, or simply prefer `/mgmt/restconf`. The RFC's own examples use `/restconf` "for simplicity" (section 1.1.6), and that is where the hard-coding habit comes from. A client that skips discovery works on the devices that happen to match and gets `404 Not Found` on the rest. So section 3.1 makes discovery a client obligation: when first connecting to a RESTCONF server, the client **MUST** determine the root of the API. **host-meta** is not a RESTCONF invention. RFC 6415 defines it as a general place where a host publishes metadata about itself, chiefly link relations pointing at services it offers. RESTCONF registers a link relation type named `restconf` (RFC 8040 section 11.1) and reuses the mechanism, so the same document can describe other services on the host without confusing a RESTCONF client. ## The discovery exchange 1. **Open TLS to the device.** RESTCONF requires a transport with integrity and confidentiality and MUST NOT be used over HTTP without TLS (section 2.1). 2. **Fetch host-meta.** Send `GET /.well-known/host-meta`. That well-known URI is registered by **RFC 6415 (Web Host Metadata)**; RFC 8040's examples ask for the XRD form with `Accept: application/xrd+xml`. 3. **Pick the `restconf` link.** The reply is an XRD document containing `<Link>` elements. The device **MUST** return exactly one link with `rel='restconf'`; if the document carries other relations, only that one matters for RESTCONF. 4. **Use the href as the path prefix.** Every later RESTCONF request starts with it: `{href}/data/...`, `{href}/operations/...`, `{href}/yang-library-version`. 5. **Optionally read the root.** A GET on the href returns `ietf-restconf:restconf` with its three children, a cheap check that the prefix is right before any edit. ## Rules that follow from the mechanism - **One RESTCONF server per endpoint.** host-meta lives at a fixed path per host:port and names one root, so a host running two RESTCONF servers must put them on different ports (section 3.1). - **Other link relations are ignored.** The XRD may describe other services on the same host; a RESTCONF client reads only `restconf`. - **Two encodings of host-meta exist.** RFC 6415 also registers `/.well-known/host-meta.json`, a JSON form (JRD) it RECOMMENDS servers offer alongside XRD. RFC 8040 itself only shows the XRD request. - **Versioning rides on the same document.** RFC 8040 defines RESTCONF version 1 and expects a future version to use a different root resource, located by a different link relation; the server advertises every version it supports in host-meta (section 1.5). - **Discovery stops at the root.** RESTCONF has no discovery of data resources; below the root, the client builds paths from the YANG modules listed in `ietf-yang-library`, starting with `{href}/yang-library-version`. ## Diagnosing a failed first request | Symptom | Likely cause | What to do | |---|---|---| | `404` on `/restconf/data/...` | the root is elsewhere | run host-meta discovery and use its href | | `404` on `/.well-known/host-meta` | wrong host:port, or a server not meeting RFC 8040's discovery requirement | confirm the RESTCONF endpoint; a conforming server must answer | | works on one device, `404` on another | client assumed one platform's path | discover per device, never per fleet | | worked yesterday, `404` today | root moved behind a new proxy or port | rediscover on failure; a cached root is a client convenience, not something the RFC promises stays valid | ## What an interviewer is listening for - The word **MUST** on the client side: discovery is not optional politeness. - The exact pieces: `/.well-known/host-meta`, an XRD `<Link>`, `rel="restconf"`, href used as a prefix. - The consequence most people miss: one RESTCONF server per host:port. - No confusion with the data model: discovery finds where the API is, the YANG library says what it contains. - A sensible client design: discover once per device, keep the href with the device record, and rediscover when a request under it returns `404`.

  • Why can a single host:port expose only one RESTCONF server?
    Root discovery reads one fixed resource, `/.well-known/host-meta`, per endpoint, and that document MUST carry exactly one `restconf` link relation. Two RESTCONF servers behind the same host:port would need two roots in one document, which the rule forbids, so RFC 8040 section 3.1 notes each concurrent server must use a different port.
  • How does host-meta let a device offer a future RESTCONF version alongside version 1?
    RFC 8040 section 1.5 expects a new RESTCONF version to live under a different root resource, located by a different link relation. The server lists every version it supports in its host-meta document; a version-1 client keeps following `rel='restconf'` and ignores the rest.

saying these in an interview costs you the question

  • RFC 8040 fixes the RESTCONF root at /restconf, so discovery can be skipped.
  • The root is found in the ietf-restconf-monitoring capabilities list.
  • host-meta may return several restconf links and the client picks one.
  • Discovering the root also discovers every data resource under it.
  • A host can run several RESTCONF servers on one port under different roots.