RFC8040 RESTCONF协议规范中文翻译
Internet Engineering Task Force (IETF) A. Bierman Request for Comments: 8040 YumaWorks Category: Standards Track M. Bjorklund ISSN: 2070-1721 Tail-f Systems K. Watsen Juniper Networks January 2017
RESTCONF协议
摘要
本文档描述了一种基于HTTP的协议，此协议提供用于访问YANG定义的数据的编程 接口，使用 NETCONF 定义的数据存储。
- 引言 需要一种标准机制，允许以模块化和可扩展的方式访问网络设备的配置数据、状 态数据、特性数据模型的远程过程调用操作（RPC），事件通知。 本文档定义了一种基于HTTP[RFC7230]的协议，叫做”RESTCONF”，用于配置由YANG 版本 1[RFC6020]或者YANG 版本1.1[RFC7950]定义的数据，使用NETCONF定义的 datastore概念。 NETCONF定义了配置datastore，以及用于访问这些datastore的，CRUD操作。NETCONF 也定义了调用这些操作的协议。YANG语言定义了datastore内容、配 置数据、状态数据、RPC操作以及事件通知的语法和语义。 RESTCONF使用HTTP方法来提供对包含YANG定义的数据的概念datastore的CRUD操作 ，兼容实现了NETCONF datastore的服务器。 如果RESTCONF服务端与NETCONF服务端共存，那么这些操作都是与NETCONF协议的协议 交互；这些交互在第1.4节描述。RESTCONF服务端可能使用操作资源访问特定的 datastore，就像第3.6节描述的那样。RESTCONF协议不会指定任何强制的操作 资源。每一个操作资源的语义决定datastore可以是否访问，以及如何访问。 配置数据和状态数据都以资源暴露，可以通过GET方法获取。表示配置数据的资源 可以用DELETE、PATCH、POST、PUT方法修改。数据以XML[W3C.REC-xml-20081126] 或者JSON[RFC7159]编码。 由YANG的rpc和action语句定义的特定数据模型的RPC操作可以用POST方法调用。由YANG 的notification语句定义的事件通知也可以访问。
1.1. 术语
本文档中的关键字”MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, 和 “OPTIONAL” 由[RFC2119]解释。
1.1.1. NETCONF
下面的术语定义在[RFC6241]中: o 候补配置datastore o 配置数据 o datastore o 配置datastore o 运行配置datastore o 启动配置datastore o 状态数据 o 用户
1.1.2. HTTP
下面的术语定义在[RFC3986]中: o fragment o 路径 o 查询
下面的术语定义在[RFC7230]中: o 头字段 o 消息体 o 请求行 o 请求URI o 状态行
下面的术语定义在[RFC7231]中: o 方法 o 请求 o 资源
下面的术语定义在[RFC7232]中:
o 实体标签
1.1.3. YANG
下面的术语定义在[RFC7950]中: o action o container o data node o key leaf o leaf o leaf-list o list o mandatory node o ordered-by user o presence container o RPC operation o top-level data node
1.1.4. NETCONF Notifications
下面的术语定义在[RFC5277]中: o notification replay
1.1.5. 术语
本文档是使用下面的术语： o API资源: 建模RESTCONF的根资源，以及访问YANG定义的内容的子资源。它是 由”ietf-restconf”模块中定义的”yang-api” YANG数据模板定义的。 o client: RESTCONF客户端。 o 数据资源: 建模YANG数据节点的资源。它由YANG的数据定义语句定义。 o datastore资源: 使用NETCONF datastore的概念建模可编程接口。默认情况下，RESTCONF 方法访问服务端底层datastore实现的统一视图。它定义为API资源的子资源。 o 编辑操作: 使用POST、PUT、PATCH、DELETE方法对数据资源的RESTCONF操作。这与 NETCONF编辑操作（即，一个”nc:operation”属性值：”create”, “replace”, “merge”, “delete”, 或”remove”）不同。 o 事件流资源: 表示一个SSE(Server-Sent Events)事件流的资源。资源的内容由媒体类型 “text/event-stream”的文本组成，由SSE规范定义[W3C.REC-eventsource-20150203]。事件流 将在第3.8节描述。 o 媒体类型: HTTP在”Content-Type”和”Accept”头字段中用互联网媒体类型[RFC2046]来提供 开放的、可扩展的数据类型和类型协商。 o NETCONF客户端: 实现了NETCONF协议的客户端。在[RFC6241]中称为客户端。 o NETCONF服务端: 实现了NETCONF协议的服务端。在[RFC6241]中称为服务端。 o 操作: RESTCONF的概念操作，来源于HTTP方法、请求URI、头字段、消息体。 o 操作资源: 建模由YANG rpc和action语句定义的特定数据模型的操作的资源。用POST方法调用。 o patch: 目标datastore或者数据资源上的PATCH方法。消息体内容的媒体类型会识别使用的patch类型。 o 普通patch: PATCH方法是用特定的媒体类型，参见第4.6.21节。它可用于简单的merge编辑操作。 媒体类型由请求的Content-Type指定，”application/yang-data+xml” 或 “application/yang-data+json”。 o 查询参数: 请求URI中query部分的参数（及其值，如果有的话）。 o 资源类型: 本文档中定义的RESTCONF资源类，包括”api”, “datastore”, “data”, “operation”, “schema”, 或 “event stream”。 o RESTCONF能力: 特殊服务端发布的可选的RESTCONF协议特性。这个特性IANA注册的NETCONF能力URI 标识，并以第9.3节定义的”capability” leaf-list发布。 o RESTCONF客户端: 实现RESTCONF协议的客户端。 o RESTCONF服务端: 实现RESTCONF协议的服务端。 o 检索请求: 使用GET或者HEAD方法的请求。 o schema资源: 客户端使用GET方法检索YANG schema的资源。它用媒体类型”application/yang”表示。 o server: 一个RESTCONF服务端。 o “stream”列表: 一组描述服务端事件流资源的数据资源实例。这些信息定义在 “ietf-restconf-monitoring”模块的”stream”列表。它可以使用目标资源 “{+restconf}/data/ietf-restconf-monitoring:restconf-state/streams/ stream”来检索。”stream”列表包含每一个stream的信息，例如获取事件流数据的URL。 o stream资源: 一个事件流资源。 o 目标资源: 与特定消息有关的资源，由请求URI的”path”部分标识。 o yang-data扩展: 遵循”yang-data”扩展语句的YANG外部语句。yang-data扩展用于YANG数据 模板的YANG数据结构。实现这些数据结构不是为了成为配置datastore的一部分或者作为 服务端的运行状态，所以不能使用通常的YANG数据定义语句。 o YANG数据模板: 将协议消息组件建模为概念数据结构的YANG schema。这允许消息以与编码 独立的方式来定义。每一个YANG数据模板都以用”yang-data”扩展定义的。可以为YANG定义遵循特殊的 YANG数据模板实例的表示。XML表示定义在YANG 版本1.1中[RFC7950]， 由媒体类型 “application/yang-data+xml”支持。JSON表示定义在”YANG数据模型的JSON编码”[RFC7951]中， 由媒体类型”application/yang-data+json”支持。
1.1.6. URI模板和示例
在本文档中，URI模板[RFC6570]语法”{+restconf}”指的是RESTCONF根资源外的一个例子。参见 3.1节了解细节。
为了简单起见，本文档中的所有例子使用”/restconf”作为发现的RESTCONF API根路径。本文档中的 许多例子都是基于附录A.1中定义的”example-jukebox” YANG模型。
为了显示清晰，本文档例子中的许多协议头行和消息体文本都分为多行显示。当某行以(“")结束时， 表示该行换行只是为了显示目的。可以认为它是加入到下一行，删除下一行的反斜杠、后换行、前导空格。
1.1.7. 树形图
本文档使用简单的数据模型的图形表示。这些树形图的符号意思是： o “[“和”]”包含key列表。 o 在数据节点名字前的缩写：”rw”意思是配置数据（读写）, “ro”意思是状态数据 (只读), 和 “x” 意思是操作资源 (可执行)。 o 数据节点名字之后的符号：”?”意思是可选节点，”!”意思是presence容器，”*“表示list或者leaf-list。 o 圆括号包含的是choice和case节点，case节点也以(“:”)标记。 o 省略号(“…“)表示子树的内容，没有显示
1.2. NETCONF功能的子集
RESTCONF不需要镜像所有NETCONF协议的功能，但是它需要兼容NETCONF。 RESTCONF达到这个目的，实现了NETCONF协议提供的能力子集。例如，消除datatore和显示锁。 RESTCONF使用HTTP方法来实现与NETCONF等价的操作，提供基本的概念资源的CRUD操作。 HTTP POST, PUT, PATCH, 和DELETE方法用于编辑由YANG数据模型表示的数据资源 。 这些的基本操作允许RESTCONF客户端修改running配置。 RESTCONF不打算代替NETCONF，而是提供一个HTTP接口，并遵循REST原则[REST-Dissertation]， 以兼容NETCONF datastore模型。
1.3. 数据模型驱动的API
RESTCONF结合了HTTP的简单性与schema驱动的API的可预测性和自动化潜力。如果知道 服务端使用的YANG模块，那么客户端可以推断出所有可管理的资源URL、所有RESTCONF请 求和响应的合理结构。这个策略消除了需要服务端提供的响应中包含超媒体的要求，在 Roy Fielding的博士论文[REST-Dissertation]中描述的应用状态链接引擎。因为客户端 能够根据YANG模块确定它需要的链接。
RESTCONF运用YANG library [RFC7895]，允许客户端发现服务端YANG模块的一致性信息 ，如果客户端想要使用它的话。
服务端可以选择性地支持它使用的YANG模块的检索，这些YANG模块由YANG library来标识。 参见第3.7节了解更多信息。
特定数据模块的RPC操作和datastore内容的URI都可以基于YANG模块定义来预测。
RESTCONF协议运行在YANG数据建模语法定义的概念datastore上。服务端会列出它支持的所有 YANG模块，通过”ietf-yang-library”模块[RFC7895]来实现。服务端必须实现”ietf-yang-library” 模块，它必须在”modules-state/module”列表中标识服务端使用的所有YANG模块。概念datastore 内容，特定数据模型的RPC操作，事件通知都是由这组YANG模块标识的。
根据YANG的”config”语句，数据分为配置数据和非配置数据。与数据排序有关的行为由YANG “ordered-by”语句定义。非配置数据也称为“状态数据”。
RESTCONF datastore编辑模型是非常简单和直接的，非常类似于NETCONF中:writable-running 能力的行为。每一次对datastore资源中的数据资源的编辑都是在编辑成功完成时激活的。
1.4. 与NETCONF共存
RESTCONF可以在支持NETCONF协议的设备上实现。
下图说明了RESTCONF服务的与NETCONF服务端共存的系统组件：
+-----------+ +-----------------+
| Web app | <-------> | |
+-----------+ RESTCONF | network device |
| |
+-----------+ | +-----------+ |
| NETCONF | <-------> | | datastore | |
| Client | NETCONF | | | |
+-----------+ | +-----------+ |
+-----------------+
下图说明了实现了RESTCONF服务端的设备没有NETCONF服务端的系统组件：
+-----------+ +-----------------+
| Web app | <-------> | |
+-----------+ RESTCONF | network device |
| |
+-----------------+
有关编辑操作上NETCONF协议和RESTCONF协议是由交互的。有可能RESTCONF服务端正在 使用锁，即使RESTCONF不能操作锁。在这种场景中，RESTCONF协议不会授权访问datastore 中的数据资源。
如果NETCONF服务端支持:writable-running，所有对配置节点{+restconf}/data的编辑, 都是在运行配置datastore中执行的。URI模板”{+restconf}”在1.1.6节定义。
另外，如果设备支持:candidate，那么所有对配置节点{+restconf}/data的编辑，都会在 candidate配置datastore中执行。candidate datastore必须在每一次编辑成功之后自动 提交到running datastore。任何来自其它资源的candidate编辑都会被提交。如果已确认的 提交过程正在进行中，那么任何新的提交就会成为确认提交。如果NETCONF服务端需要一个 “persist-id”参数来完成已确认提交的过程，那么RESTCONF编辑操作必须以”409 Conflict” 状态行失败。在这种情况下，error-tag为”in-use”。
如果NETCONF服务端支持:startup，那么在”running” datastore已经因为RESTCONF编辑操作 被改变之后，RESTCONF服务必须自动更新non-volatile启动配置datastore。
如果RESTCONF操作修改的datastore的锁被NETCONF客户端持有，那么RESTCONF编辑操作必须 失败，以”409 Conflict”状态行。返回的error-tag为”in-use”。
1.5. RESTCONF可扩展性
RESTCONF有两个扩展机制： o 协议版本 o 可选的能力
本文档定义的RESTCONF版本为1。如果这个协议的未来版本定义了，那么那个文档会说明如何标识 RESTCONF的新版本号。 它希望使用不同的RESTCONF根资源，这将使用不同的链接关系来定位， 参加3.1节。 服务端会在host-meta中发布它支持的所有协议版本。 这个例子中，服务的支持RESTCONF版本1和虚构的版本2。 客户端可能会发送下面的请求：
GET /.well-known/host-meta HTTP/1.1
Host: example.com
Accept: application/xrd+xml
服务端的响应可能如下所示：
HTTP/1.1 200 OK
Content-Type: application/xrd+xml
Content-Length: nnn
<XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>
<Link rel='restconf' href='/restconf'/>
<Link rel='restconf2' href='/restconf2'/>
</XRD>
RESTCONF也支持服务定义的可选能力，这些能力由9.3节定义的”ietf-restconf-monitoring”模块 列出。本文档定义一些查询参数，参见4.8节。每一个可选的参数都有一个相应的能力URI， 参见9.1.1节定义，如果服务端支持，它会发布。
“capability” leaf-list可以标识任何服务端扩展。当前，这个扩展机制用于标识支持的可选参数， 但是它不限制只能用于这个目的。例如，9.1.2节定义的”defaults” URI是一个强制的URI，以标识 服务端的默认处理行为。
新的子资源类型可以用能力来标识，如果它是可选的实现。强制的协议特性和新的资源类型需要新的 RESTCONF协议版本。
- 传输协议
2.1. 完整性和机密性
HTTP [RFC7230]一个应用层协议，它可能堆叠到任何可靠的传输层协议上。RESTCONF定义在HTTP之上， 但是由于传输信息的敏感性，RESTCONF要求传输层协议提供数据完整性和机密性。RESTCONF服务端必须 支持传输层安全性协议（TLS，[RFC5246]），应该遵守[RFC7525]。 RESTCONF协议一定不能用于没有使用TLS协议的HTTP。
RESTCONF不需要特定的HTTP版本。然而，推荐所有的实现至少支持HTTP/1.1 [RFC7230]。
2.2. 使用X.509v3证书HTTPS
考虑到普遍支持TLS的HTTP[RFC7230]，RESTCONF实现必须支持”https” URI scheme，IANA分配的默认端口为443。
当与RESTCONF客户端建立TLS连接时，RESTCONF服务端必须提供基于X.509v3的证书。使用基于X.509v3的证书要 与TLS上的NETCONF[RFC7589]保持一致。
2.3. 校验证书
RESTCONF客户端必须要么使用X.509证书路径校验[RFC5280]来验证RESTCONF服务端的TLS证书的完整性， 要么用受信机制获得证书与服务端的TLS证书比较。如果X.509证书路径校验失败，或者已经存在的X.509 证书与从受信机制获得证书不匹配，那么连接必须终止，参见[RFC5246]7.2.1节。
2.4. 服务端身份认证
RESTCONF客户端必须根据[RFC2818]的3.1节检查服务端的身份。
2.5. 客户端身份认证
RESTCONF服务端必须验证客户端，访问任何受保护的资源。如果RESTCONF没有认证，那么服务端应该 发送带有”401 Unauthorized”状态行的HTTP响应，就像[RFC7235]3.1节定义的那样。 在这种场景下， error-tag的值为”access-denied”。
要鉴定客户端，RESTCONF服务端应该需要基于TLS客户端证书的证明([RFC5246]的7.4.6节)。如果基于证书的 证明不可行(例如，因为不能构建需要的客户端KPI)，那么可能会使用HTTP认证。 在后面的这个场景下，必须使用[RFC7235] 5.1节定义的HTTP认证scheme注册表中定义的认证scheme。
服务端也可能支持客户端证书和HTTP客户端认证方案的组合。如果处理这种组合由实现来决定。从证书机制中 推断出的RESTCONF客户端身份今后称为”RESTCONF username”，服从NETCONF访问控制模型(NACM) [RFC6536]。 当客户端证书存在时，RESTCONF用户名必须由[RFC7589]第7节定义的算法来推导。对应其它的场景，当使用HTTP 认证时，RESTCONF用户名必须由HTTP认证方案提供。
- 资源
RESTCONF协议在层次结构的资源上运行，以顶级API资源开头（3.1节）。每一个资源表示设备上的一个可管理组件。
资源可以认为是一个数据以及数据上允许的方法的集合。它可以包含嵌套的子资源。子资源类型以及允许的方法 是针对特定的数据模型的。
资源的表示与媒体类型标识符有关，由HTTP响应消息中的”Content-Type”头字段表示。 资源可以有一种或多种表示，每一种表示都与不同的媒体类型相关。当资源的表示在HTTP消息中发送时， 相关的媒体类型会在”Content-Type”头中给定。一个资源可以包含0个或多个嵌套的资源。 只要父资源存在，子资源就可以独立的创建和删除。
RESTCONF资源可以通过一组本文档中定义的URI访问。服务端支持的YANG模块决定特定数据模型的RPC操作， 顶级数据节点，服务端支持的事件通知消息。
RESTCONF协议不包含数据资源发现机制。相反，服务端发布的YANG模块中的定义用于构造RPC操作或者数据资源标识符。
3.1. 根资源发现
与[RFC7320]中定义的最佳实践保持一致，RESTCONF允许在部署时指定RESTCONF API的位置。 当第一次连接RESTCONF服务端时，RESTCONF客户端必须确定RESTCONF API的根。设备必须返回唯一正确的 “restconf”链接关系。
客户端通过”/.well-known/host-meta”资源([RFC6415])发现这个根，使用包含”restconf”属性的元素：
示例：返回/restconf:
客户端可能发送下面的请求： GET /.well-known/host-meta HTTP/1.1 Host: example.com Accept: application/xrd+xml
服务端可能返回如下的响应：
HTTP/1.1 200 OK
Content-Type: application/xrd+xml
Content-Length: nnn
<XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>
<Link rel='restconf' href='/restconf'/>
</XRD>
在发现了RESTCONF API根之后，客户端必须在任何后续请求RESTCONF资源时， 使用这个值作为请求URI路径的初始部分。
在这个例子中，客户端会使用路径”/restconf”作为RESTCONF的根资源。
示例：返回/top/restconf:
客户端可能发送下面的请求：
GET /.well-known/host-meta HTTP/1.1
Host: example.com
Accept: application/xrd+xml
服务端可能会返回如下的响应：
HTTP/1.1 200 OK
Content-Type: application/xrd+xml
Content-Length: nnn
<XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>
<Link rel='restconf' href='/top/restconf'/>
</XRD>
在这个例子中，客户端使用路径”/top/restconf”作为RESTCONF的根资源。
客户端现在可以确定服务端支持的操作资源。
示例：支持自定义的”play”操作
客户端可能发送下面的请求：
GET /top/restconf/operations HTTP/1.1
Host: example.com
Accept: application/yang-data+json
服务端可能返回如下的响应：
HTTP/1.1 200 OK
Date: Thu, 26 Jan 2017 20:56:30 GMT
Server: example-server
Cache-Control: no-cache
Last-Modified: Thu, 26 Jan 2017 16:00:14 GMT
Content-Type: application/yang-data+json
{ "operations" : { "example-jukebox:play" : [null] } }
在扩展资源描述符(XRD)包含多个链接关系，那么只有名字为”restconf”的关系是跟本文档相关的。
注意，由于根资源发现机制，任何给定的端点(host:port)只能支持一个RESTCONF服务端。这限制了在一个主机 上并发运行的RESTCONF服务端的数量，因为每一个服务端必须使用一个不同的端口。
3.2. RESTCONF媒体类型
RESTCONF协议定义了特定应用的媒体类型，来标识遵循特定YANG结构的schema的数据。 本文档为YANG数据定义了XML和JSON序列化媒体类型。其它的文档可能会定义其它的媒体类型。 “application/yang-data+xml”媒体类型在11.3.1节定义。 “application/yang-data+json”媒体类型在11.3.2节定义。
3.3. API资源
API资源包含RESTCONF datastore资源和操作资源的根资源。它是顶级的资源，位于{+restconf}， 媒体类型为”application/yang-data+xml”或”application/yang-data+json”。
API资源的YANG树形图：
+---- {+restconf}
+---- data
| ...
+---- operations?
| ...
+--ro yang-library-version string
“yang-api” YANG数据模板使用”ietf-restconf”模块中定义的”yang-data”扩展定义，参见第8节。 它指定了API资源内的概念子资源的结构和语法。
API资源可以用GET方法检索。
响应中表示”ietf-restconf”模块根的{+restconf}根资源名必须标识”ietf-restconf”YANG模块。 例如，请求以JSON格式GET 根资源 root resource name used in responses representing the root of the “ietf-restconf”“/restconf”，将返回名为”ietf-restconf:restconf”的API资源表示。
API资源包含下面的子资源：
+----------------------+---------------------------------+
| 子资源 | 描述 |
+----------------------+---------------------------------+
| data | 包含所有的数据资源 |
| operations | 特定数据模型的操作 |
| yang-library-version | "ietf-yang-library"模块日期 |
+----------------------+---------------------------------+
RESTCONF API资源