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
  4. <XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>
  5. <Link rel='restconf' href='/restconf'/>
  6. </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
  4. <XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>
  5. <Link rel='restconf' href='/top/restconf'/>
  6. </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
  7. { "operations" : { "example-jukebox:play" : [null] } }

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

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