Migrating REST API to RESTCONF

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:

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

General Guidance for REST to RESTCONF API migration

• /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+xml. The 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>