Submitting a POST Request to the REST API
Use an HTTP POST request to send single or multiple RPC requests to the REST API. You can use the POST request to do device configuration.
For a single rpc
command, the general format of the endpoints is:
scheme://device-name:port/rpc/method[@attributes]/params
scheme
:http
orhttps
method
: The name of any Junos OSrpc
command. Themethod
name is identical to the tag element. For more information, see the Junos XML Protocol Operations, Processing Instructions, and Response Tags in the Junos XML Management Protocol Developer Guide and the Junos XML API Operational Developer Reference.params
: Optional parameter values (name[=value]
).
To authenticate your request, submit the base64-encoded username and password included in the Authorization header:
curl -u "username:password" http://device-name:port/rpc/get-interface-information
To specify rpc
data as a query string in the URI for POST requests, submit the query data in the POST body. In such cases you can specify the Content-Type
as text/plain
or application/xml
, as shown in these equivalent cURL calls:
curl -u "username:password" http://device-name:port/rpc/get-interface-information --header "Content-Type: text/plain" –d "interface-name=cbp0" curl -u "username:password" http://device-name:port/rpc/get-interface-information --header "Content-Type: application/xml" –d "<interface-name>cbp0</interface-name>"
For both single and multiple RPC commands, HTTP Accept headers can be used to specify the return format using one of the following Content-Type values:
application/xml (the default)
application/json
text/plain
text/html
For example, the following cURL call specifies an output format of JSON:
curl -u "username:password" http://device-name:port/rpc -d <get-software-information /> –header "Accept: application/json"
You can also specify the output format using the optional format
attribute:
curl -u "username:password" http://device-name:port/rpc -d "<get-software-information format=application/json'/>"
The default Content-Type for POST requests containing arguments in the body is application/xml. If you want to use any other content, such as a query string, you can specify a Content-Type of text/plain. Specify the format
attribute in configuration commands.
When executing multiple rpc
commands in a single request, the general format of the endpoint is:
scheme://device-name:port/rpc
The RPCs must be provided as XML data in the POST body. The Content-Type for the response is multipart/mixed, with boundary and subtype associated with the output from each RPC execution. The format specified in the Accept header is used as the output format for each of the RPCs if they are missing a format
attribute. If an Accept header is not specified and no format
attribute is specified in a given RPC, the default output format is XML. For example, to send a single HTTP request to execute the RPCs get-software-information
and get-interface-information
, submit a POST request to /rpc
with "Auth: Basic <base64hash>"
, "Content-Type: application/xml"
. The POST body would contain:
<get-software-information/><get-interface-information/>
Here is a cURL call using this POST body:
curl -u "username:password" http://device-name:port/rpc -d "<get-software-information/><get-interface-information/>"
The output from the request, containing XML as the default, would appear as follows:
HTTP/1.1 200 OK Content-Type: multipart/mixed; boundary=fkj49sn38dcn3 Transfer-Encoding: chunked Date: Thu, 20 Mar 2014 11:01:27 GMT Server: lighttpd/1.4.32 --fkj49sn38dcn3 Content-Type: application/xml <software-information> <host-name>...</host-name> ... </software-information> --fkj49sn38dcn3 Content-Type: application/xml <interface-information> <physical-interface>...</physical-interface> </interface-information> --fkj49sn38dcn3--
You can also specify the output format for each of the elements in the POST body. For example, the following request emits JSON for the get-interface-information
RPC and plain text for the get-software-information
RPC:
curl -u "username:password" http://device-name:port/rpc -d "<get-interface-information/><get-software-information format='text/plain'/>" —header "Accept: application/json"
When executing multiple RPCs, if an error occurs, the default behavior is to ignore the error and continue execution. If you want to exit when the first error is encountered, specify the stop-on-error
flag in the URI. For example, the following request configures the device and terminates if an error is encountered:
curl -u "username:password" http://device-name:port/rpc?stop-on-error=1 -d "<lock-configuration/> <load-configuration> <configuration><system><hostname>foo</hostname></system></configuration> </load-configuration> <commit/> <unlock-configuration/>"