Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 

Understanding the REST API

 

The REST API is a Representational State Transfer (REST) interface that enables you to securely connect to Juniper Networks Junos operating system (Junos OS) devices, execute remote procedure calls (rpc commands), use a REST API Explorer GUI enabling you to conveniently experiment with any of the REST APIs, and use a variety of formatting and display options, including JavaScript Object Notation (JSON).

The REST API can be configured on Junos OS devices using commands available under the [edit system services rest] hierarchy level. Once configured, the REST API becomes available as the rest service, a REST-based interface that enables you to submit rpc commands to the device from a remote location, and supports GET and POST requests. With the REST API you can:

  • Use GET requests to submit rpc commands.

  • Use POST requests to submit information via rpc commands.

  • Retrieve configuration information in XML, ASCII (plain text), or JSON.

  • Retrieve operational data in XML, ASCII, or JSON.

At the [edit system services rest] hierarchy level, you can configure and secure the REST API service on a Junos OS device; set up IP addresses, port numbers, server certificates, control parameters, and trace options; and enable a REST API explorer tool that enables you to try the REST APIs using a convenient GUI.

The following CLI display options are available:

  • A display json option is added to the | (pipe) command. For example, the CLI command show interfaces | display json displays the interfaces in JSON notation.

  • A format="json" option is added to NETCONF server commands to return operational information in JSON notation.

Note

Starting in Junos OS Release 17.3R1, OpenConfig supports the operational state emitted by daemons directly in JSON format in addition to XML format. To configure JSON compact format, specify the following CLI command:

set system export-format state-data json compact.

This CLI command converts XML format to compact JSON format. Else, it emits the JSON in non-compact format.

Note

The REST API incoming request payload size cannot exceed 1174KB.

Workaround: Chunk the incoming REST API requests into a smaller size.

The REST API supports HTTP Basic Authentication, and all requests require a base64-encoded username and password included in the Authorization header. Both HTTP and HTTPS support are available:

  • You can use HTTP to exchange content using clear text if you do not need a secure connection.

  • We recommend that you use HTTPS to exchange encrypted content using one of the available cipher suites. You can configure the REST API to require server authentication without client authentication, or you can configure mutual authentication.

Once the REST API is configured on the device, new REST endpoints are available for executing either single rpc commands via GET or POST requests, or executing multiple rpc commands via a single POST request. See Submitting a GET Request to the REST API and Submitting a POST Request to the REST API for more information.

The REST API also provides a GUI called the REST API Explorer, which allows you to easily and quickly learn how to use the REST API. It is disabled by default, and can be enabled by specifying set system services rest enable-explorer. To learn more about the REST API Explorer, see Example: Using the REST API Explorer.

Release History Table
Release
Description
Starting in Junos OS Release 17.3R1, OpenConfig supports the operational state emitted by daemons directly in JSON format in addition to XML format. To configure JSON compact format, specify the following CLI command:

set system export-format state-data json compact.

This CLI command converts XML format to compact JSON format. Else, it emits the JSON in non-compact format.