Use POST to retrieve data from endpoints which require parameters¶

There are API endpoints that return state, configuration, or similar data which require parameters to control the output. In these cases, rather than using GET, the request type is POST.

For example, there is an endpoint to retrieve BGP status, but it also has several parameters to change or filter the output.

Item	Value
Request Type	`-X POST` (submit input parameters)
Content Type	`-H "Content-Type: application/yang-data+json"`
RESTCONF API location	`/restconf/operations/netgate-bgp:bgp-show`
Parameter Namespace	`netgate-bgp:input`
Parameter: `request`	`neighbors`
Parameter: `family`	`ipv4`
Parameter: `vrf-id`	`default`

Assemble these parameters into a query with cURL or similar tools:

$ curl -f --cert ~/tnsr/tnsr-restconf-client.crt \
  --key ~/tnsr/tnsr-restconf-client.key \
  --cacert ~/tnsr/tnsr-restconf-CA.crt \
  -H "Content-Type: application/yang-data+json" \
  -X POST \
  -d '{"netgate-bgp:input":[{"request":"neighbors","family":"ipv4","vrf-id":"default"}]}' \
  https://tnsr.example.com/restconf/operations/netgate-bgp:bgp-show

Output (trimmed for brevity):

{
  "netgate-bgp:output": {
    "stdout": "BGP neighbor is 10.2.222.2[...]"
  }
}

Handling shell output in RESTCONF responses¶

The previous example output from BGP status has output that is formatted for a terminal and not broken up into separate JSON fields. To improve handling of these types of responses, extract the data from the response and process it separately.

One way to accomplish this is with a JSON processing utility such as jq:

$ curl -s -f --cert ~/tnsr/tnsr-restconf-client.crt \
  --key ~/tnsr/tnsr-restconf-client.key \
  --cacert ~/tnsr/tnsr-restconf-CA.crt \
  -H "Content-Type: application/yang-data+json" \
  -X POST \
  -d '{"netgate-bgp:input":[{"request":"neighbors","family":"ipv4","vrf-id":"default"}]}' \
  https://tnsr.example.com/restconf/operations/netgate-bgp:bgp-show | \
  jq -r '."netgate-bgp:output" .stdout' | \
  grep 'BGP state'

After processing through jq and selecting the output node from the JSON response it is returned to typical terminal style output without the JSON encoding. At that point it can be run through typical shell utilities such as grep, as in the example above.

The output from this command is a single line indicating the state of one BGP peer:

BGP state = Established, up for 00:14:12