RESTCONF Operation Methods
RESTCONF supports OPTIONS, HEAD, GET, POST, PATCH, PUT and DELETE methods which can be used to query and modify resources. If RESTCONF request sent from the client contains data to be operated on a specific method, the data will be placed in either XML or JSON format in the Body.
The following sections describe the usage of each method with specific examples, where HTTP client tools Postman and PyCharm are used.
OPTIONS
Function description: The client sends the OPTIONS method to discover which methods the server supports for a particular resource (for example, GET, POST, DELETE).
URL: https://device_ip:port/restconf/data
Example: Request from RESTCONF client using Postman
The response result is:
In the result,
“Allow” shows the RESTCONF methods supported by the server. In this example, the RESTCONF methods supported by the server are OPTIONS, HEAD, GET, POST, PATCH, PUT and DELETE.
“Accept-Patch” shows the data formats supported by the PATCH method. In this example, the data formats can be accepted are application/yang-data+xml and application/yang-data+json.
HEAD
Function description: The HEAD method is sent by the client to query whether the configuration data and status data exist, only the Header fields that would be returned for the comparable GET method, without the response message-body. It is supported for all resources that support the GET method.
URL: https://device_ip:port/restconf/data/modulename:node
Example: Request from RESTCONF client using Postman
The response result is:
If the query data exists, the "200 OK" status code is returned, you can use GET method to get the data information.
GET
Function description: The GET method is sent by the client to retrieve data and metadata for a resource.
URL: https://device_ip:port/restconf/data/modulename:node
Example 1: Request from RESTCONF client using Postman
As shown in above figure,
“Content-Type” field in the header defines the body format of request messages.
“Accept” field defines the body format of response messages.
If set “Accept” field to “application/yang-data+json”, the response result received is in JSON format:
If set “Accept” field to “application/yang-data+xml”:
The response result received is in XML format:
Example 2: Request from RESTCONF client using PyCharm
import requests
from requests.auth import HTTPBasicAuth
import json
import urllib3
urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
AUTH = HTTPBasicAuth('admin', '12345678')
ACCEPT_TYPE = 'application/yang-data+json'
CONTENT_TYPE = 'application/yang-data+json'
HEADERS = { 'Accept': ACCEPT_TYPE, 'Content-Type': CONTENT_TYPE }
def get_request(url):
response = requests.get(url, auth=AUTH, headers=HEADERS, verify=False)
print("URL:", url)
print("ret code:", response.status_code)
if response.status_code in [200]:
print("Successful")
else:
print("Error in API Request")
output = json.loads(response.text)
print(output)
url = "https://10.10.51.186/restconf/data/vlans:vlans"
get_request(url)
The response result is:
URL: https://10.10.51.186/restconf/data/vlans:vlans
ret code: 200
Successful
{'vlans:vlans': {'vlan-id': [{'id': '1000', 'vlan-name': 'test1000'}]}}
POST
Function description: The POST method is sent by the client to create top-level resource or sub-resource.
URL: https://device_ip:port/restconf/data
Example 1: Request from RESTCONF client using Postman
Data format defined in the header:
The expected settings are written to the body in JSON format:
Response is:
The result can be shown on the managed network device:
admin@PICOS# The configuration has been changed by user root
DELTAS:
protocols {
static {
route 8.8.8.0/24 {
next-hop 10.10.10.10
}
}
}
admin@PICOS# show protocols static
route 8.8.8.0/24 {
next-hop 10.10.10.10
}
Example 2: we can write the body in XML format in PyCharm:
import requests
from requests.auth import HTTPBasicAuth
import json
import urllib3
urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
AUTH = HTTPBasicAuth('admin', '12345678')
ACCEPT_TYPE = 'application/yang-data+json'
CONTENT_TYPE = 'application/yang-data+xml'
HEADERS = { 'Accept': ACCEPT_TYPE, 'Content-Type': CONTENT_TYPE }
def get_request(url):
payload = '<static xmlns="http://pica8.com/xorplus/static-routes" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">' \
'<route>' \
'<name>8.8.8.0/24</name>' \
'<next-hop>' \
'<ip-address>10.10.10.10</ip-address>' \
'</next-hop>' \
'</route>' \
'</static>'
response = requests.post(url, auth=AUTH, headers=HEADERS, verify=False,data=payload)
print("URL: ", url)
print(response.status_code)
if response.status_code in [201]:
print("Successful")
else:
print("Error in API Request")
#output = json.loads(response.text)
print(response.text)
url = "https://10.10.51.186/restconf/data"
get_request(url)
The response result is:
URL: https://10.10.51.186/restconf/data
201
Successful
PATCH
Function description: The PATCH method is sent by the client to modify the configuration data.
URL: https://device_ip:port/restconf/data/modulename:node
Example 1: Request from RESTCONF client using Postman
Data format defined in the header:
The expected settings are written to the body in XML format:
Response received is:
Then the configuration has been set to the device.
admin@PICOS# show vlans
vlan-id 1000 {
vlan-name: "test1000"
}
admin@PICOS# The configuration has been changed by user root
DELTAS:
vlans {
vlan-id 2000 {
vlan-name: "test2000"
}
}
admin@PICOS#
admin@PICOS# show vlans
vlan-id 1000 {
vlan-name: "test1000"
}
vlan-id 2000 {
vlan-name: "test2000"
}
Example 2: we can write the body section in JSON format in PyCharm
import requests
from requests.auth import HTTPBasicAuth
import json
import urllib3
urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
AUTH = HTTPBasicAuth('admin', '12345678')
ACCEPT_TYPE = 'application/yang-data+json'
CONTENT_TYPE = 'application/yang-data+json'
HEADERS = { 'Accept': ACCEPT_TYPE, 'Content-Type': CONTENT_TYPE }
def get_request(url):
payload = '{"vlans:vlans":{"vlan-id":[{"id":"2000","vlan-name":"test2000"}]}}'
response = requests.patch(url, auth=AUTH, headers=HEADERS, verify=False, data=payload)
print("URL:", url)
print("ret code:", response.status_code)
if response.status_code in [204]:
print("Successful")
else:
print("Error in API Request")
#output = json.loads(response.text)
print(response.text)
url = "https://10.10.51.186/restconf/data/vlans:vlans"
get_request(url)
The response result is:
URL: https://10.10.51.186/restconf/data/vlans:vlans
ret code: 204
Successful
PUT
Function description: The PUT method is sending the latest configuration to the device to replace the data on the device.
URL: https://device_ip:port/restconf/data/modulename:node
Example 1: Request from RESTCONF client using Postman
Data format defined in the header:
The expected settings are written to the body in JSON format:
Response is:
The expected configuration takes effect and the old configuration is deleted.
admin@PICOS# show vlans
vlan-id 1000 {
vlan-name: "test1000"
}
vlan-id 2000 {
vlan-name: "test2000"
}
admin@PICOS# The configuration has been changed by user root
DELETIONS:
vlans {
vlan-id 1000
vlan-id 2000
}
DELTAS:
vlans {
vlan-id 3000 {
vlan-name: "test3000"
}
}
admin@PICOS# show vlans
vlan-id 3000 {
vlan-name: "test3000"
}
Example 2: we can do it in PyCharm:
import requests
from requests.auth import HTTPBasicAuth
import json
import urllib3
urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
AUTH = HTTPBasicAuth('admin', '12345678')
ACCEPT_TYPE = 'application/yang-data+json'
CONTENT_TYPE = 'application/yang-data+json'
HEADERS = { 'Accept': ACCEPT_TYPE, 'Content-Type': CONTENT_TYPE }
def get_request(url):
payload = '{"vlans:vlans":{"vlan-id":{"id":"3000","vlan-name":"test3000"}}}'
response = requests.put(url, auth=AUTH, headers=HEADERS, verify=False, data=payload)
print("URL:", url)
print("ret code:", response.status_code)
if response.status_code in [204]:
print("Successful")
else:
print("Error in API Request")
#output = json.loads(response.text)
print(response.text)
url = "https://10.10.51.186/restconf/data/vlans:vlans"
get_request(url)
The response result is:
URL: https://10.10.51.186/restconf/data/vlans:vlans
ret code: 204
Successful
DELETE
Function description: The DELETE method is used to delete the node or data specified by the URL.
There are several application scenarios are supported when using DELETE method:
Scenario 1: Delete all the configurations of a specified module
URL: https://device_ip:port/restconf/data/modulename:node
Example: Request from RESTCONF client using Postman
On the managed network device, we can see that the configurations under module “static-route” is removed:
admin@PICOS# show protocols static
route 8.8.8.0/24 {
next-hop 10.10.10.10
}
admin@PICOS# The configuration has been changed by user root
DELETIONS:
protocols {
static {
}
}
admin@PICOS# show protocols static
ERROR: try to show a non existing configure tree node.
Scenario 2: Delete specified list member
URL: https://device_ip:port/restconf/data/modulename:node/container
Example: Request from RESTCONF client using Postman
On the managed network device, we can see that vlan-id=1000 in the vlan-id list is removed:
admin@PICOS# show vlans
vlan-id 1000 {
vlan-name: "test1000"
}
vlan-id 2000 {
vlan-name: "test2000"
}
admin@PICOS# The configuration has been changed by user root
DELETIONS:
vlans {
vlan-id 1000
}
admin@PICOS# show vlans
vlan-id 2000 {
vlan-name: "test2000"
}
Scenario 3: Delete specified container
URL: https://device_ip:port/restconf/data/modulename:node[/parant-container]/child-container
Example: Request from RESTCONF client using Postman
On the managed network device, we can see that child container family in specified parent container interface is removed:
admin@PICOS# show interface gigabit-ethernet xe-1/1/6
mtu: 2000
family {
ethernet-switching {
}
}
admin@PICOS# The configuration has been changed by user root
DELETIONS:
interface {
gigabit-ethernet "xe-1/1/6" {
family {
}
}
}
admin@PICOS# show interface gigabit-ethernet xe-1/1/6
mtu: 2000
Scenario 4: Delete specified leaf
URL: https://device_ip:port/restconf/data/modulename:node/container/leaf
Example: Request from RESTCONF client using Postman
On the managed network device, we can see that leaf “vlan-name” is removed:
admin@PICOS# show vlans
vlan-id 2000 {
vlan-name: "test2000"
}
admin@PICOS# The configuration has been changed by user root
DELETIONS:
vlans {
vlan-id 2000 {
vlan-name: "test2000"
}
}
admin@PICOS# show vlans
vlan-id 2000 {
}
Scenario 5: Restores a leaf that has a default value to its default value
URL: https://device_ip:port/restconf/data/modulename:node/container/leaf=configured_value
Example: Request from RESTCONF client using Postman
On the managed network device, we can see that the MTU configuration is removed and restored to the default value 1514:
admin@PICOS# show interface gigabit-ethernet xe-1/1/6
mtu: 2000
admin@PICOS# The configuration has been changed by user root
DELETIONS:
interface {
gigabit-ethernet "xe-1/1/6" {
mtu: 2000
}
}
admin@PICOS# show interface gigabit-ethernet xe-1/1/6
Copyright © 2024 Pica8 Inc. All Rights Reserved.