Overview

Confd REST API is deprecated from Confd version 7.4.5. Currently, RBBN SBC Core uses Confd 7.3.2 (or earlier versions) to support REST APIs to configure the system. As part of release 11.1, SBC Core moved to Confd version 7.7 or later.

This document highlights the nature of the changes so that users can start planning/implementing the migration.

REST vs RESTCONF

RESTCONF RFC: https://datatracker.ietf.org/doc/html/rfc8040

Tail-f/Cisco Note on Migration: https://info.tail-f.com/confd-legacy-rest-api-to-restconf-migration

RESTCONF Overview: 

https://ultraconfig.com.au/blog/restconf-tutorial-everything-you-need-to-know-about-restconf-in-2020/

https://www.cisco.com/c/en/us/td/docs/ios-xml/ios/prog/configuration/166/b_166_programmability_cg/restconf_prog_int.pdf

Differences

There is no better way than looking at the examples when it comes to learning APIs or differences. Please take a look at the Examples section below for some real examples. The following table gives a high-level view of the differences:


REST

RESTCONF

Media Typesapplication/vnd.yang.data+xml
application/vnd.yang.data+json
application/yang-data+xml
application/yang-data+json
Data-storesconfig, running, candidate, operational, operations,  rollbacks

data, operations

(shouldn't impact our users as we support only config and operations only with REST)

Data-store Paths(in URI)

api/config

api/operational

restconf/data/

restconf/operations

Action Commands"_operations" to the path leading to the action
Module Name in URIN/A

Yang module name needs to be specified when using restconf/data/

E.g. restconf/data/sonusAddressContext:addressContext=default

Examples
POST

curl -kisu 'admin:myPassword123@' -X POST -H \

     'Content-Type: application/vnd.yang.data+xml' \

     https://172.19.201.17/api/config --data '...'

curl -kisu 'admin:myPassword123@' -X POST -H

     'Content-Type: application/yang-data+xml' \

     https://172.29.85.47/restconf/data/ --data '...'

DELETE

curl -kisu 'admin:myPassword123@' -X DELETE \

     https://172.19.201.17/api/config/addressContext/ac_1

curl -kisu 'admin:myPassword123@' -X DELETE -H \

     "Accept: application/yang-data+xml" \

     https://172.29.85.47/restconf/data/sonusAddressContext:addressContext=ADDR_CONT_1

PUT

curl -kisu 'admin:myPassword123@' -X PUT -H \

     'Content-Type: application/vnd.yang.data+xml' \

     https://172.19.201.17/api/config/addressContext/ac_1 --data '...'

curl -kisu 'admin:myPassword123@' -X PUT -H \

     'Content-Type: application/yang-data+xml' \

     'https://172.29.85.47/restconf/data/sonusAddressContext:addressContext=addressContext2' --data '...'

PATCH

curl -kisu admin:myPassword123@ -X PATCH -H \

     'Content-Type: application/vnd.yang.data+xml' \

     https://172.19.201.17/api/config/ --data '...'

curl -kisu 'admin:myPassword123@' -X PATCH -H \

     'Content-Type: application/yang-data+xml'  \

     'https://172.29.85.47/restconf/data/sonusAddressContext:addressContext=default/sonusZone:zone=zone3' --data '...'

GET

curl -kisu 'admin:myPassword123@' -X GET \

     https://172.19.201.17/api/operational/system/softwareUpgradeStatus

curl -kisu 'admin:myPassword123@' -X GET \

     'Content-type: application/yang-data+xml' \

     https://172.29.85.47/restconf/data/sonusSystem:system/softwareUpgradeStatus

Action Command

curl -kisu 'admin:myPassword123@' -X POST -H \

     'Content-Type: application/vnd.yang.data+xml' \

     https://172.19.201.17/api/config/system/admin/MY-SBC/_operations/saveConfig --data '...'

curl -kisu admin:myPassword123@ -X POST -H \

     'Content-type: application/yang-data+xml' \

      https://172.29.85.47/restconf/operations/system/admin=vsbcSystem/saveConfig  --data '...'

Note: So far didn't come across any cases where the data/body format is different.

General Guidance for REST to RESTCONF API migration

Note

Below Mapping/guidance on URI change is not tested for all APIs.


  • /api/config in REST will map to /restconf/data/ in RESTCONF.
  • /api/operational in REST will map to /restconf/data/ in RESTCONF.
  • If REST URI contains '_operations', RESTCONF URI will starts as: /restconf/operations/
  • Key or resource in RESTCONF is denoted with = rather than with /

           Eg: /api/config/addressContext/ac_1 will change to: /restconf/data/sonusAddressContext:addressContext=ac_1

  • module name is required in RESTCONF along with resource(check example above). An API to list module names based on yang definition will be provided for reference.
  • The RESTCONF specification states that a result containing multiple instances (e.g a number of list entries) is not allowed if XML encoding is used. The reason for this is that an XML document can only have one root node. To remedy this, a HTTP GET request can make use of the "Accept:" media type: application/vnd.yang.collection+xmlThe result will then be wrapped with a "collection" element.

  • The nodes which are added as symlink need not require the module name in RESTCONF call, since it is treated as a node present under the current YANG module. For example, eventLog is defined under sonusGen2EventLog.yang module, but it is linked to oam under sonusOrca.yang. The RESTCONF is as follows:  curl -kisu admin:myPassword123@ -X PATCH -H "Content-Type: application/yang-data+xml" How to Configure RESTCONF
  1. Enable restconf by adding <restconf> section in confd.conf file and update CFG_RESTCONF in webui section.

    <restconf>
       <enabled>true</enabled>
       <rootResource>restconf</rootResource>
    </restconf>
    <webui>
          <enabled>true</enabled>
          <transport>
              <tcp>
                  <!--CFG_RESTCONF--><enabled>true</enabled>
                  <ip>127.0.0.1</ip>
                  <port>8008</port>
                  <extraIpPorts>[::1]</extraIpPorts>
              </tcp>
          </transport>
     </webui>

    Note: The rootResource needs to be defined in confd.conf. This will be used in apache config and in every curl request. /restconf is similar to /api in REST API.

  2. Reload the confd daemon in SBC.  
  3. Make changes in Apache configuration file (/etc/apache2/sites-available/EMA) to allow RESTCONF API requests in port 443.

       Add the below sub-element in <VirtualHost *:443> element 

    <Location /restconf>
            ProxyPass         http://127.0.0.1:8008/restconf
            ProxyPassReverse  http://127.0.0.1:8008/restconf
            RequestHeader     set SSL_CLIENT_S_DN      "%{SSL_CLIENT_S_DN}s"
            RequestHeader     set SSL_CLIENT_I_DN      "%{SSL_CLIENT_I_DN}s"
            RequestHeader     set SSL_SERVER_S_DN_OU   "%{SSL_SERVER_S_DN_OU}s"
            RequestHeader     set SSL_CLIENT_VERIFY    "%{SSL_CLIENT_VERIFY}s"
            RequestHeader     set SSL_CLIENT_S_DN_CN   "%{SSL_CLIENT_S_DN_CN}s"
    
            RewriteEngine On
            RewriteCond %{REQUEST_METHOD} !^(GET|PUT|POST|PATCH|DELETE) [NC]
            RewriteRule .* - [F]
    
            ForceType        application/yang-data+xml
    
        </Location>
    
    
  4. Restart the apache server running in SBC. /etc/init.d/apache2 restart
  5. There is only one datastore in RESTCONF, the unified datastore. All references to the specific datastore resources in the legacy REST API, such as /running, /candidate, and /config, need to be modified to use /data in RESTCONF. Also the usage of /operational in the legacy REST API needs to use the content modifier on /data in RESTCONF, /data?content=nonconfig.

    Additional configurations in apache server to deny the requests to other datastores.

        <Location /restconf/candidate>
            Deny from all
        </Location>
    
        <Location /restconf/running>
            Deny from all
        </Location>
     
    	<Location /restconf/config>
            Deny from all
        </Location>
     
        <Location /restconf/rollbacks>
            Deny from all
        </Location>