Tip

This is the documentation for the 24.06 version. Looking for the documentation of the latest version? Have a look here.

Troubleshooting RESTCONF

Errors when attempting to use HTTP POST to create objects

Due to the way the RESTCONF RFC and related standards define the format of data it can be confusing that a client cannot take the data from a GET query response for a given URL and submit the result to the exact same URL with POST.

This happens because the GET request returns the contents wrapped in a container at the level of the requested URL, whereas POST requires only the body content, not the outer container. However, in both cases the top-level object must be qualified with a namespace.

Depending on the use case there are two ways to make such queries work.

See also

Refer to RESTCONF Service Setup with Certificate-Based Authentication and NACM for more information on making RESTCONF queries.

In this example, a client fetches the contents of a URL with GET

Query:

GET /restconf/data/netgate-kea:kea-config/dhcp4-server/Dhcp4/lease-database

Response:

{
   "netgate-kea:lease-database": {
      "lfc-interval": 3600
   }
}

Note

Note the outer container and namespace which match the URL: netgate-kea:lease-database.

Given this starting point there are two potential ways to submit a query which would create this object if it were deleted or otherwise did not exist.

Method 1: Same URL, adjusted payload

The first workaround can POST to the given URL but it requires adjusting the payload body. Remove the outer container and add appropriate namespaces to each item in the top level:

Query:

POST /restconf/data/netgate-kea:kea-config/dhcp4-server/Dhcp4/lease-database

Data Payload:

{
   "netgate-kea:lfc-interval": 3600
}

Note

Note the lack of outer container and that the value has a namespace prepended.

Method 2: Adjusted URL, same payload

The second workaround can POST using the original payload, but it requires adjusting the URL and removing the last component of the path.

Query:

POST /restconf/data/netgate-kea:kea-config/dhcp4-server/Dhcp4/

Data Payload:

{
   "netgate-kea:lease-database": {
      "lfc-interval": 3600
   }
}

Note

Note that the payload is identical to the response from GET but the URL has the last component of the original path, lease-database, removed.

RESTCONF API Errors

Errors returned by the TNSR RESTCONF API may come from either the RESTCONF Server or API Endpoints.

The RESTCONF service may not return a response body in all error cases, but it will return a proper HTTP response code. When using scripts to interact with the API, test the return code first before inspecting the response body.

When using curl to interact with the API, use curl -f to exit with a non-zero error when the server sends back an HTTP error code. The response body is suppressed by curl -f when it detects an error code, however, curl -f will print the HTTP error code and text instead. On curl version 7.76.0 and later, use curl --fail-with-body which will exit with a non-zero status, print the HTTP error, and print the response body if one is present.

The following list includes common errors and their resolutions:

Error code 404 / Not Found:

Error returned by the HTTP server when the URL does not exist. For example, if the client intended to use the API but requested a URL that did not start with /restconf/data/.

Error code 415 / Unsupported Media Type:

Error returned by the HTTP server when the client did not submit a proper content type with a PUT or PATCH request (e.g. Content-Type: application/yang-data+json)

api-path keys do not match data keys:

Error returned by the API when a client attempted a PUT or PATCH operation without fully qualifying the target. For example, the client tried to PATCH but the submitted data did not contain enough information to uniquely identify a target.

Instance does not exist:

Error returned by the API when a client requests an entry from a valid area but where a specific entry does not exist.

Unknown element:

Error returned by the API when a client requests data from an invalid container.

‘<name>’: Expected prefix:name:

Error returned by the API when a RESTCONF URL does not include the namespace prefix.

No such yang module prefix:

Error returned by the API when the module name (e.g. netgate:<something>) does not exist.

Top-level JSON object [name] is not qualified with namespace which is a MUST according to RFC 7951:

Error returned when performing an operation such as POST where the top-level object does not have a namespace. For example, sending POST data with only {"lfc-interval":3600} when it should be qualified with a namespace: {"netgate-kea:lfc-interval":3600}.