RESTCONF Protocol

RESTCONF is intentionally a subset of NETCONF, not a replacement. It eliminates explicit locking and multi-datastore management (candidate, startup) to achieve RESTful simplicity, while remaining compatible with NETCONF's datastore model and access control (NACM).

netconf, yang

RESTCONF uses a data-model-driven API where the client can derive all management resource URLs from YANG modules, eliminating the need for HATEOAS links in responses. Because the YANG schema determines the resource structure, the server does not need to embed hypermedia links.

netconf, yang, http

Root resource discovery via '/.well-known/host-meta' was chosen so deployments can place the RESTCONF API at any path, rather than mandating a fixed '/restconf' root. This also means a single host:port endpoint can only support one RESTCONF server, since discovery returns exactly one 'restconf' link relation.

http, netconf

If a NETCONF client holds an active lock on a datastore that a RESTCONF operation would modify, the RESTCONF edit MUST fail with '409 Conflict' and error-tag 'in-use'. RESTCONF cannot acquire or release NETCONF locks.

netconf, yang

If the NETCONF server supports :startup, the RESTCONF server MUST automatically update the non-volatile startup configuration datastore after any successful RESTCONF edit to the running datastore. This ensures persistence across device reboots.

netconf, yang

When co-located with a NETCONF server using :candidate, RESTCONF edits are performed in the candidate datastore and MUST be automatically committed to running immediately after each successful edit. If a confirmed commit with a 'persist-id' is in progress, the RESTCONF edit MUST fail with '409 Conflict' and error-tag 'in-use'.

netconf, yang

If a leaf or leaf-list is missing from the configuration and a YANG-defined default exists, the server MUST use the YANG-defined default. When a GET targets such an uninstantiated leaf or leaf-list, the server MUST return the default value, ignoring its 'basic-mode' setting.

netconf, yang

RESTCONF implementations MUST support the 'https' URI scheme (default port 443). Servers MUST present an X.509v3-based certificate when establishing a TLS connection.

tls, pkix, http, security

RESTCONF requires transport-layer integrity and confidentiality. A RESTCONF server MUST support TLS and SHOULD adhere to RFC 7525. The RESTCONF protocol MUST NOT be used over HTTP without TLS.

http, tls, security, netconf, yang

The RESTCONF client MUST either use X.509 certificate path validation (RFC 5280) or match the server certificate via a trusted mechanism. If both fail, the connection MUST be terminated.

tls, pkix, security

The RESTCONF server MUST authenticate client access to any protected resource. If the client is not authenticated, the server SHOULD return '401 Unauthorized'. TLS client certificates are the preferred authentication mechanism; HTTP authentication schemes MAY be used if certificate-based authentication is not feasible.

security, tls, http

The RESTCONF username MUST be derived using the algorithm defined in Section 7 of RFC 7589 when a client certificate is presented. For HTTP authentication, the RESTCONF username MUST be provided by the HTTP authentication scheme used. The username is subject to NACM (RFC 6536).

security, netconf, yang

The server MUST implement the 'ietf-yang-library' module (RFC 7895), which MUST identify all YANG modules used by the server in the 'modules-state/module' list. This defines the set of supported data nodes, RPC operations, and event notifications.

netconf, yang, registry

The server MUST implement the OPTIONS method. The 'Accept-Patch' header field MUST be supported and returned in the OPTIONS response. The server MUST support the HEAD method for all resources that support GET.

http, netconf

The server MUST maintain a unique opaque entity-tag for the {+restconf}/data datastore resource and MUST return it in the 'ETag' header for retrieval requests. The entity-tag is only affected by configuration data resources and MUST NOT be updated for non-configuration data changes.

netconf, yang, http

The server MUST NOT allow any RESTCONF operation for resources that the client is not authorized to access. RESTCONF is compatible with NACM (RFC 6536); the server maps resource paths to YANG instance identifiers to apply NACM access control rules.

security, netconf, yang

When a POST creates a resource successfully, the server MUST return '201 Created' with no response body and MUST include a 'Location' header identifying the created child resource. If the resource already exists, the server MUST return '409 Conflict' with error-tag 'resource-denied'.

http, netconf, yang

When first connecting, a RESTCONF client MUST determine the root of the RESTCONF API by retrieving '/.well-known/host-meta' (RFC 6415) and using the Link element with the 'restconf' relation. There MUST be exactly one 'restconf' link relation returned.

http, netconf, yang

Operation resources represent YANG 'rpc' or 'action' statements. RPC operations are invoked via 'POST {+restconf}/operations/<module>:<operation>'; YANG actions are invoked via 'POST {+restconf}/data/<data-resource-identifier>/<action>'. If no output section exists, the server MUST return '204 No Content'.

netconf, yang, http

RESTCONF defines nine query parameters: 'content' (config/nonconfig/all), 'depth' (subtree depth), 'fields' (field selection), 'filter' (notification filter), 'insert' (ordered-by insertion point), 'point' (reference point for insert), 'start-time'/'stop-time' (notification replay window), and 'with-defaults' (default value handling). Each optional parameter has a corresponding capability URI.

netconf, yang, http

RESTCONF supports Server-Sent Events (SSE) for event stream resources. Clients subscribe to notifications by issuing a GET on the event stream URI. Event streams function according to NETCONF Event Notifications (RFC 5277). Available streams are discovered from the '{+restconf}/data/ietf-restconf-monitoring:restconf-state/streams' list.

netconf, yang, http

The 'errors' YANG data template models error information returned as message-body in server responses. The 'ietf-restconf' module defines the 'yang-errors' template with an 'errors' container; each error includes error-type, error-tag, optional error-path (XPath), and error-message fields.

netconf, yang, http, json

The 'ietf-restconf-monitoring' module provides the 'restconf-state' tree with two sub-trees: 'capabilities' (list of supported capability URIs including optional query parameters and defaults behavior) and 'streams' (list of available event stream resources with URLs).

netconf, yang, registry

The RESTCONF API resource is the top-level resource at {+restconf} with media type 'application/yang-data+xml' or 'application/yang-data+json'. It contains three child resources: 'data' (all data resources), 'operations' (RPC operations), and 'yang-library-version' (mandatory leaf identifying the ietf-yang-library revision date).

netconf, yang, http, json

Two edit collision detection mechanisms are provided for the datastore resource: a Last-Modified timestamp and an ETag entity-tag. Any change to configuration data resources updates both. The server MUST return an error if the datastore is locked by an external source (e.g., NETCONF).

netconf, yang, http

RFC 8040 registers the following with IANA: the 'restconf' link relation type, two media types ('application/yang-data+xml' and 'application/yang-data+json'), RESTCONF capability URNs (for each optional query parameter and defaults behavior), and a 'restconf' URN sub-namespace under 'urn:ietf:params:xml:ns:yang'.

registry, netconf, yang, http

RESTCONF conveys sensitive network configuration data and therefore mandates TLS for all connections. Servers must authenticate all clients accessing protected resources, preferably via TLS client certificates. NACM (RFC 6536) is used for authorization, with RESTCONF operations mapped to equivalent NETCONF operations for access control rule application.

security, tls, netconf, yang

Data resource identifiers use a URI-encoded path following the 'api-path' ABNF: 'api-path = root *("/" (api-identifier / list-instance))'. List key values are encoded as comma-separated values after '='. Reserved characters MUST be percent-encoded per RFC 3986. Module names are prepended with a colon when crossing module boundaries.

netconf, yang, http