3.1. 根资源发现

根据[RFC7320]定义的最佳实践，RESTCONF使部署能够指定RESTCONF API的位置。当第一次连接到RESTCONF服务器时，RESTCONF客户端必须确定RESTCONF API的根。必须正好有一个由设备返回的“restconf”链接关系。

客户端通过获取“/.well-known/host-meta”资源（[RFC6415]）并使用包含“restconf”属性的<Link>元素来发现这一点：

返回/restconf示例：

客户端可能会发送以下内容：

  1. GET /.well-known/host-meta HTTP/1.1
  2. Host: example.com
  3. Accept: application/xrd+xml

服务器可能会如下回应：

  1. HTTP/1.1 200 OK
  2. Content-Type: application/xrd+xml
  3. Content-Length: nnn
  5. <XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>
  6.     <Link rel='restconf' href='/restconf'/>
  7. </XRD>

在发现RESTCONF API根后，客户端必须使用这个值作为请求URI中的路径的初始部分，在RESTCONF资源的任何后续请求中。

在这个例子中，客户端将使用路径“/restconf”作为RESTCONF根资源。

返回/top/restconf的例子：

客户端可能会发送以下内容：

  1. GET /.well-known/host-meta HTTP/1.1
  2. Host: example.com
  3. Accept: application/xrd+xml

服务器可能会如下回应：

  1. HTTP/1.1 200 OK
  2. Content-Type: application/xrd+xml
  3. Content-Length: nnn
  5. <XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>
  6.     <Link rel='restconf' href='/top/restconf'/>
  7. </XRD>

在这个例子中，客户端将使用路径“/top/restconf”作为RESTCONF根资源。

客户端现在可以确定服务器支持的操作资源。在这个例子中，支持一个自定义的“play”操作：

客户端可能会发送以下内容：

  1. GET /top/restconf/operations HTTP/1.1
  2. Host: example.com
  3. Accept: application/yang-data+json

服务器可能会如下回应：

  1. HTTP/1.1 200 OK
  2. Date: Thu, 26 Jan 2017 20:56:30 GMT
  3. Server: example-server
  4. Cache-Control: no-cache
  5. Last-Modified: Thu, 26 Jan 2017 16:00:14 GMT
  6. Content-Type: application/yang-data+json
  8. { "operations" : { "example-jukebox:play" : [null] } }

如果可扩展资源描述符（XRD）包含多个链接关系，则只有名为“restconf”的关系与此规范相关。

请注意，由于根资源发现机制，任何给定的端点（主机：端口）只能支持一个RESTCONF服务器。这限制了可以在主机上同时运行的RESTCONF服务器的数量，因为每个服务器都必须使用不同的端口。