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.