In line with the best practices defined by [RFC7320], RESTCONF enables deployments to specify where the RESTCONF API is located. When first connecting to a RESTCONF server, a RESTCONF client MUST determine the root of the RESTCONF API. There MUST be exactly one "restconf" link relation returned by the device.

The client discovers this by getting the "/.well-known/host-meta" resource ([RFC6415]) and using the <Link> element containing the "restconf" attribute:

Example returning /restconf. The client might send the following:

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

The server might respond as follows:

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>


After discovering the RESTCONF API root, the client MUST use this value as the initial part of the path in the request URI, in any subsequent request for a RESTCONF resource.

Apache configuration


Apache mod_headers is used to provide support for the RESTCONF client discovery of the root of the RESTCONF API.

## enable mod_headers to use the following directives
> a2enmod headers

The client discovers root of the RESTCONF API by getting the "/.well-known/host-meta" resource and using the <Link> element containing the "restconf" attribute, for example. Below is the part of the Virtual Host configuration file that demonstrates what configurations is needed to setup root discovery. Add this section to your Virtual Host configuration file.

#### CHANGE '/var/www/yang-api' to match DocumentRoot if needed
<Directory /var/www/yang-api/.well-known>
    SetHandler default-handler
    ForceType 'application/xrd+xml'

    ## enable mod_headers to use the following directives
    ## > a2enmod headers
    Header unset Etag
    Header unset Last-Modified
    Header unset Accept-Ranges
    Header set Cache-Control no-cache
    Header merge Cache-Control no-store
    Header set Pragma no-cache

    ## Ony GET is allowed
    <Limit POST PATCH DELETE PUT>
        Order deny,allow
        Deny from all
    </Limit>

    AllowOverride all
    Order allow,deny
    allow from all
</Directory>

Example of host-meta file that should be installed at the /var/www/yang-api/.well-known/host-meta, by default:

<?xml version='1.0' encoding='UTF-8'?>
<XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>
  <Link rel='restconf' href='/restconf' />
</XRD>


NGINX configuration


To allow clients to access the "/.well-known/host-meta" file on a RESTCONF site served by NGINX you need to ensure that your "root" location is correct (/var/www/yang-api in the example below) and you need to add "/.well-known" as a location in your restconf site configuration:


  location /.well-known {
  }


Below is a full site configuration file example that allows access to the host-meta file. Note the root location and the .well-known location:


##
# You should look at the following URL's in order to grasp a solid understanding
# of Nginx configuration files in order to fully unleash the power of Nginx.
# http://wiki.nginx.org/Pitfalls
# http://wiki.nginx.org/QuickStart
# http://wiki.nginx.org/Configuration
#
# Generally, you will want to move this file somewhere, and start with a clean
# file but keep this around for reference. Or just disable in sites-enabled.
#
# Please see /usr/share/doc/nginx-doc/examples/ for more detailed examples.
##

# Default server configuration
#
server {
  listen 80 default_server;
  listen [::]:80 default_server;

  # SSL configuration
  #
  # listen 443 ssl default_server;
  # listen [::]:443 ssl default_server;
  #
  # Note: You should disable gzip for SSL traffic.
  # See: https://bugs.debian.org/773332
  #
  # Read up on ssl_ciphers to ensure a secure configuration.
  # See: https://bugs.debian.org/765782
  #
  # Self signed certs generated by the ssl-cert package
  # Don't use them in a production server!
  #
  # include snippets/snakeoil.conf;

  root /var/www/yang-api;

  # Add index.php to the list if you are using PHP
  index index.html index.htm index.nginx-debian.html;

  # need to install fcgiwrap to use RESTCONF
  # set SCRIPT_FILENAME to the location of the restconf program
  location /restconf {
    include fastcgi_params;
            fastcgi_param  SCRIPT_NAME restconf;
            fastcgi_param  SCRIPT_FILENAME /var/www/yang-api/restconf;
            fastcgi_pass unix:/var/run/fcgiwrap.socket;
  }
       
  location = /favicon.ico {
          log_not_found off;
  }

  location /.well-known {
  }

  location / {
    # First attempt to serve request as file, then
    # as directory, then fall back to displaying a 404.
    try_files $uri $uri/ =404;
  }
}