Representational State Transfer (REST)
Overview
Remote access API statements
REST statements are submitted through HTTP GET, DELETE, PUT, and POST commands by using the format of HTTP-command REST-statement, as in the following example:GET /rest/conf
The specific result of any REST statement depends on the HTTP command that is used to submit the statement to the remote DANOS vRouter.
The command reference material for REST statements in this guide includes the HTTP commands that are used to submit them; that is, the description uses the complete combination of HTTP-command REST-statement to describe how to interact with the remote DANOS vRouter.
API prerequisites
Using the DANOS vRouter Remote Access API 2.0 requires the following:
DANOS vRouter has HTTPS enabled
set service httpsValid username and password on the DANOS vRouter
System to generate the HTTPS requests to the DANOS vRouter
Interacting with the API
In general, interaction with the DANOS vRouter consists of an HTTPS request to the system that is followed by a response from the system. Each request includes in its HTTP header a command, the address of the remote system, the format of the response body that is expected, the specification version number, and a base64 encoding of a valid username-and-password pair (conforming to the basic access authorization originally defined in RFC 1945); these credentials are validated on the remote system's authorization system.
The following sample interaction shows a simple request and response.
Clear the counters on dp0p1p1 on 10.0.0.232. The dnlhdHRhOnZ5YXR0YQ== character string is the base64 encoding of the vyatta:vyatta username-and-password pair.
POST /rest/op/clear/interfaces/dataplane/dp0p1p1/counters
Host: 10.0.0.232
Accept: application/json
Vyatta-Specification-Version: 0.1
Authorization: Basic dnlhdHRhOnZ5YXR0YQ==System response:
HTTP/1.1 201 Created
Transfer-Encoding: chunked
Content-Type: application/json
Location: rest/op/3479DEF17C6AF4D1
Date: Fri, 19 Feb 2019 21:27:57 GMT
Server: lighttpd/1.4.19For testing purposes, a simple way to create a request is to use a command such as curl, although any tool that allows you to construct an HTTPS request (such as wget, a browser, python, and so on) suffices.
For example, to generate the request that is shown in the previous example by using the curl command, you enter the command that is shown in the following example.
Use curl to generate an operational mode request, clear interfaces dataplane dp0p1p1 counters, by using the
vyatta:vyatta username and password pair on the DANOS vRouter at 10.0.0.232.
vyatta@R1:~$ curl -k -s -i -u vyatta:vyatta -H “content-length:0” -H “Accept: application/json” -X POST https://10.0.0.232/rest/op/clear/interfaces/dataplane/dp0p1p1/countersSystem response:
Special-character handling
Special characters that must be included within the command line of the request header must be formatted to be URL safe. For example, to set the address of dp0p1p1 to 10.0.0.231/24 by using the CLI, enter the following command in configuration mode:
set interfaces dataplane dp0p1p1 address 10.0.0.231/24
Within the API, however, the last slash character (/) is improperly parsed by the HTTP protocol, so it must be replaced by a sequence of escape characters to represent it. The escape encoding for the slash character is %2F; therefore, the URL-safe character string must be represented as follows:
rest/conf/set/interfaces/dataplane/dp0p1p1/address/10.0.0.231%2F24
See https://tools.ietf.org/html/rfc1738#section-2.2 for details on URL character encoding.
Response processing
The response header contains the HTTP status code.
Before processing the response body, you should check that the request is successful by ensuring that the HTTP status code is a 200-level (that is, 2xxOK) response code. The Content-Type information returned in the response header should also be checked to verify that it is correct.
Response bodies of three types can be returned in response to a request:
Empty body
JSON-formatted body
Plain text body
The body of the response is returned and its format depends on the requested HTTP Content-Type and the command that is issued through the API.
Responses to requests that initiate actions (for example, to initiate the show version command) typically have empty bodies.
Responses to requests that retrieve data (for example, a list of active operational processes) have JSON-formatted bodies.
Responses to requests that contain operational mode command output (for example, the output from the show version command) have plain-text bodies.
JSON responses vary with the command that is issued. Additional command status codes can also be returned in the body of the response. The following example shows a JSON-formatted response body—in this case, the currently active operational mode processes.
JSON responses follow standard JavaScript object construction where elements are hash entries, arrays, or nested combinations of entries and arrays. The response body that is shown previously has the following characteristics.
There is a single hash: “process.” It points to an array of hashes.
Each element of the array represents a distinct operational mode process (in this example, there are two of them) and contains information about that process.
For each process, the response shows the user who initiated the command, time the command was initiated, number of updates that have been retrieved, ID of the process, and command that was executed (or is currently executing).
Processing of JSON-formatted responses is well supported by using support libraries that are available in most programming languages. Further information is located at http://www.json.org.
Configuration mode
The configuration mode of the DANOS vRouter Remote Access API allows you to update the system configuration of the remote DANOS vRouter. The workflow for configuration by using the API is the same as that for using the system directly: begin a configuration session, make configuration changes, commit changes, optionally view them, and save them. Configuration mode is accessed by using the rest/conf URI prefix.
In configuration mode within the API, each configuration session creates a unique session ID that is used to reference the session as the URI rest/conf/conf-id. This ID must be explicitly removed when the session is completed to release the resources that are associated with the session.
Restarting the HTTPS service invalidates operational session IDs, but does not invalidate configuration session IDs.
You can perform the following tasks:
POST /rest/confStart a configuration session and enter configuration mode.
PUT /rest/conf/<conf-id>/set/<path>Create or modify configuration information
PUT /rest/conf/<conf-id>/delete/<path>Delete configuration information
POST /rest/conf/<conf-id>/<cmd>Enter a configuration action command, such as commit, save, load, merge or show.
GET /rest/conf/<conf-id>/<path>Display configuration information
GET /rest/confList active configuration mode sessions
DELETE /rest/conf/<conf-id>Exit the specified configuration session
Session example
The following example of a Remote Access API request to a DANOS vRouter at 10.0.0.232 shows how to initiate a configuration mode session.
Request a new configuration mode session. This request is equivalent to the configure command in the CLI.
The HTTPS server that is located on port 443 receives this request and identifies it as a REST request to the configuration tree (/rest/conf ). The MIME base64-encoded username:password (in this case, dnlhdHRhOnZ5YXR0YQ== is the base64 encoding of vyatta:vyatta) is then validated. After it is validated, the request runs using the credentials of the specified user (in this case, vyatta).
At this point, the action and the remaining elements in the header determine the specific processing required for this request. For this request, the action is to POST to the root of the rest/conf tree. The path and action instruct the remote DANOS vRouter to create a new configuration session for this request and return a unique ID for this configuration session.
The response that is generated by the remote system follows.
The 201 response code indicates that the request was successful and that the remote system was able to create a new configuration tree that is associated with the ID of 2957FCA1FE3B3C. This ID is used for any further interaction with this configuration session.
The API does not place any limits on the number of configuration sessions or background processes that can be created. Clients are responsible for process management and should release resources that are not in use.
The example configuration mode session that is shown here includes the following events.
A request is made to view information about active configuration sessions to see that the new session is opened.
Configuration information is then modified, committed, and saved.
The session is ended.
Active configuration is viewed again to ensure that the session was removed.
Display the active configuration sessions. The only difference between this example and the previous example is that the POST command is replaced with the GET command.
System response. The 200 response code indicates that the request succeeded. In this case, the output (in JSON format) shows that two active configuration sessions are associated with the user that initiated the command (user “vyatta”) and each session has a unique ID. Note that the “started” and “updated” fields display the time the session started and the time it was last updated in UNIX epoch time (the number of seconds since January 1, 1970). The “modified” field indicates whether uncommitted changes exist in the configuration session.
Change the SSH port to 1011. The request is equivalent to the set service ssh port 1011 command in the CLI configuration mode. Note that the URI uses the configuration session ID that was created previously.
System response. The 200 response code indicates that the request succeeded.
Commit the configuration change. This request is equivalent to the commit command in the CLI configuration mode.
System response. The 200 response code indicates that the request succeeded. Note that the SSH daemon (sshd) was restarted because of the configuration change.
Save the active configuration. This request is equivalent to the save command in CLI configuration mode.
System response. The 200 response code indicates that the request succeeded. The message shows where the file was saved.
Terminate the configuration session. This request is equivalent to the exit command in CLI configuration mode.
System response. The 200 response code indicates that the request succeeded.
Display the active configuration sessions. GET /rest/conf
System response. The 200 response code indicates that the request succeeded. In this case, the session that is terminated no longer appears in the list of active configuration sessions. A single active configuration session remains.
Operational mode
Operational mode provides the ability to run operational mode commands remotely and display their output. Each command initiates a process that may have a finite life span (for example, show version) or may run indefinitely until explicitly stopped (for example, ping address ).
Commands with finite life spans continue to consume system resources until the client either request that the resources are released (using DELETE ) or it finishes reading the output that is generated by the command. Receiving a response code of 410 (GONE) indicates that the output has been consumed. The output that is not read remains on the system until the next reboot or until the HTTPS service is restarted.
Commands with infinite life spans must be stopped explicitly (using DELETE ). The output is removed when the process is deleted or the output has been completely read.
Operational mode requests use rest/op or rest/op/op-id as part of the URI (as opposed to rest/conf or rest/conf/session-id used in configuration mode).
You can perform the following tasks:
POST /rest/op/<path>Execute an operational mode command.
GET /rest/op/<path>Retrieve operational mode parameter definitions.
GET /rest/opDisplay a list of operational mode processes.
GET /rest/op/<process-id>Retrieve output.
DELETE /rest/op/<process-id>Terminate an operational mode process.