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.
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:
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 Types | application/vnd.yang.data+xml application/vnd.yang.data+json | application/yang-data+xml application/yang-data+json |
Data-stores | config, 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 URI | N/A | Yang module name needs to be specified when using restconf/data/ E.g. restconf/data/sonusAddressContext:addressContext=default |
Examples | ||
POST |
|
|
DELETE |
|
|
PUT |
|
|
PATCH |
|
|
GET |
|
|
Action Command |
|
|
Note: So far didn't come across any cases where the data/body format is different.
Below Mapping/guidance on URI change is not tested for all APIs.
Eg: /api/config/addressContext/ac_1 will change to: /restconf/data/sonusAddressContext:addressContext=ac_1
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.
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.
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>
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>