Query parameter

Each RESTCONF operation allows one or more query parameters to be present in the request URI. The specific parameters that are allowed depends on the resource type, and sometimes the specific target resource used, in the request.

• Query parameters can be given in any order.
• Each parameter can appear at most once in a request URI. They are optional to implement by the server and optional to use by the client
• If more than one instance of a query parameter is present, then a "400 Bad Request" status-line MUST be returned by the server.
• A default value may apply if the parameter is missing.
• Query parameter names and values are case-sensitive
• A server MUST return an error with a '400 Bad Request' status-line if a query parameter is unexpected.
• The contents of the any query parameter value MUST be encoded according to RFC3986. Any reserved characters MUST be percent-encoded, according to RFC3986.

The following are the query parameter which will be supported in this release.

• Depth
• Content
• With-Default

Depth

• The "depth" parameter is used to specify the number of nest levels returned in a response for a GET method.
• The first nest-level will be the requested data node itself.
• The value of the "depth" parameter will be either an integer between 1 and 65535, or the string "unbounded". "unbounded" is the default.
• This parameter will be only allowed for GET methods on API, datastore, and data resources
• A "400 Bad Request" status-line will be returned if it used for other methods or resource types
• To retrieve all the child resources, the "depth" parameter should be set to the default value "unbounded".
• If an unsupported value is used, the RESTCONF server must return an <rpc-error> response with an 'invalid-value' error-tag.

For example, the below mentioned URL retrieves all the child resources of the “interface”, with the default value "unbounded" set to param “depth”.

GET /restconf/data/brocade-interface:interface?depth=unbounded

Content

• This query parameter will be used to select config and non-config data resources to be retrieved.
• This will be supported only on GET methods on data store and data resources.
• A "400 Bad Request" status-line is returned if used for other methods or resource types.
• The content is mandatory and the value can be either config or non-config.
• If an unsupported value is used, the RESTCONF server MUST return an <rpc-error> response with an 'invalid-value' error-tag.

You must mention the value of the content as “config” in the URI to retrieve the configuration data.

GET /restconf/data/interface?content=config

With Default

The "with-defaults" parameter is used to specify how information about default data nodes should be returned in response to GET requests on data resources.

• The value of the “basic-mode” will be returned as trim in the "defaults" protocol capabilities URI response to mention that default values will not be retrieved
• If an unsupported value is used, the RESTCONF server must return an <rpc-error> response with an 'invalid-value' error-tag.

When data is retrieved with a <with-defaults> parameter equal to 'trim', data nodes must not be reported if they contain the schema default value.

GET  /restconf/data/interfaces/interface=eth1?with-defaults=trim   HTTP/1.1
Host: 10.24.12.77
Accept: application/yang.data+json

This is the server responds.

HTTP/1.1 200 OK
   Date: Mon, 23 Apr 2012 17:01:00 GMT
   Server: SLX-OS WWW
   Content-Type: application/yang.data+json
   {
     "example:interface": [
       {
         "name" : "eth1",
         "status" : "up"
       }
     ]
   }