NVIDIA MLNX-GW User Manual for NVIDIA Skyway Appliance v8.1.2000
NVIDIA MLNX-GW User Manual for NVIDIA Skyway Appliance v8.2.2200

MLNX-GW—JSON API

JavaScript Object Notation (JSON) is a machine-to-machine data-interchange format which is supported in MLNX-GW CLI.

The JSON API allows executing CLI commands and receiving outputs in JSON format which can be easily parsed by the calling software.

The JSON API protocol runs over HTTP/HTTPS and uses the existing web authentication mechanism.

In order to access the system via HTTP/HTTPS, an HTTP/HTTPS client is needed to send POST requests to the system.

Warning

HTTPS access to the web-based management console needs to be enabled using the command “web https enable” to allow POST requests.

The HTTPS client must first be authenticated by sending a POST request to the following URL:

Copy
Copied!
            

https://<ip-address>/admin/launch?script=rh&template=json-request&action=json-login

The POST request content should contain the following data (may also be saved as a file) in a JSON format:

Copy
Copied!
            

{  "username": "<user name>",  "password": "<user password>"  }

After a successful login, a session ID (cookie) is returned to be used for other HTTPS requests in the system.

Authentication Example

Before sending JSON HTTPS request, the user must first authenticate.

Create a JSON format file that contains the relevant login credentials. For example, add this content to a file called "post.json".

Copy
Copied!
            

{  "username": "admin",  "password": "admin"  }

Run the following from the server’s shell to create a login session ID in the file: cookiejar.

Copy
Copied!
            

curl -L -X POST -d @post.json -c cookiejar "http://<ip-address>/admin/launch?script=rh&template=json-request&action=json-login"

Upon a successful login, a reply similar to the following is received:

Copy
Copied!
            

{  "status": "OK",  "status_message": "Successfully logged-in"  }

The session ID can now be used in all other JSON HTTPS requests to the system.

If authentication fails, the following message is received:

Copy
Copied!
            

{  "status": "ERROR",  "status_message": "<Invalid username or password | Please provide username and password>"  }

You may also log in and execute commands in the same JSON request. In this case, the JSON file must be in the following format:

Copy
Copied!
            

{  "username": "<user name>",  "password": "<user password>",  "commands | cmd": ["<cli command 1>", "<cli command 2>"] | "<cli command>",  "execution_type": "sync | async"  }

Example:

Copy
Copied!
            

{  "username": "admin",  "password": "admin",  "cmd": "show fan"  }

If login is successful, the JSON API response appears. Otherwise, login failure response is presented.

Changing Initial Password Through JSON API

This section provides support for changing the default password through JSON API.

Expected input:

  • To change the initial password, the payload will be as follows:

    Copy
    Copied!
                

    { "username": "admin", "password": "admin", "initial_admin_password": "admin", "initial_monitor_password": "monitor" }

Expected outputs:

  • Admin and Monitor passwords cannot be changed because they have already been changed.

    Copy
    Copied!
                

    { "status": "ERROR", "status_message": " ‘admin’ password was already set & ‘monitor’ password was already set" }

  • Admin and Monitor passwords were changed successfully.

    Copy
    Copied!
                

    { "status_message": " <‘admin’ password was updated successfully> & <‘monitor’ password was updated successfully> " }

  • Admin and Monitor passwords were not updated.

    Copy
    Copied!
                

    { "status": "OK", "status_message": "’admin’ password was updated successfully & ‘monitor’ password was updated successfully" }

  • One of the passwords of either Admin or Monitor was changed, while the other remained the same.

    Copy
    Copied!
                

    { "status": "<ERROR|OK>", "status_message": " < Initial password for the ‘admin’ password was already set | ‘admin’ password was updated successfully> " }

  • When the payload does not have initial passwords, check change-password nodes to see if there is no updated password return in this JSON payload.

    Copy
    Copied!
                

    { "status": "ERROR", "status_message": “Please set the default password for ‘admin’ account by using initial password parameters” }

When there is no issue with the login, flow will proceed without needing this step.

JSON API Logout

To log out, conduct the following steps.

  1. Perform a POST operation on URL (the request should contain the session cookie).

    Copy
    Copied!
                

    [gateway_ip]/script=rh&template=json-request&action=json-logout

  2. The gateway will remove the session and return the following JSON in the response text (in case of error, content will be relevant to the error).

    Copy
    Copied!
                

    { "status": "OK", "status_message": "Successfully logged-out" }

  3. Make sure there is no cookie. A request with an invalid cookie will respond that the cookie is invalid.

Example:

To log out, use the “curl” tool.

Copy
Copied!
            

curl -b cookiejar "http://[gateway-ip]/admin/launch?script=rh&template=json-request&action=json-logout

After successful authentication, the HTTPS client can start sending JSON requests. All requests (POST and GET) should be sent to the following URL:

After the request is handled in the system the HTTPS client receives a JSON response with an indication of the request execution result. If there is data resulting from the request, it is returned as part of the response.

See “JSON Request Format” for the CLI request format and “JSON Response Format” for the reply format.

JSON Execution Requests

JSON execution requests are HTTPS POST requests that contain CLI commands to be executed in the system.

Execution request can contain a single command or multiple commands to be executed.

  • Single command execution request format:

    Copy
    Copied!
                

    { "cmd": "<CLI command to execute>" }

    Example:

    Copy
    Copied!
                

    { "cmd": "show interfaces ethernet 1/2" }

  • Multiple command execution request format:

    Copy
    Copied!
                

    { "commands":["<CLI cmd 1>", "<CLI cmd 2>", … , <CLI cmd n>] }

    Example:

    Copy
    Copied!
                

    { "commands": [ "show interfaces ib 1/1", "show interfaces ethernet 1/2" ] }

In case of a multiple command request, the execution of the commands is done in the order they appear in the execution list. Note that the execution of a multiple command request will be stopped upon first failure. That is, in case the execution of one of the commands fails, none of the remaining commands will be executed.

Execution Types

Execution requests can be either synchronous (default) or asynchronous.

Synchronous requests will wait for a JSON response from the system. The synchronous request has a defined wait time after which the user will receive a timeout response. The timeout for a synchronous request is configurable by the user and is 30 seconds by default (see the CLI command “json-gw synchronous-request-timeout”).

Asynchronous requests will return immediately after sending the request with a reply containing a “job_id” key. The user can use the given job ID to later query for request status and execution results. Queries for asynchronous request results are guaranteed to be accessible up to 60 seconds after the request has been completed. After the result has been successfully queried it will be deleted and will no longer be accessible (even if the result is not 60 seconds old).

To specify the execution type, the user needs to add the following key to the JSON execution request.

Copy
Copied!
            

"execution_type":"<async|sync>"

Example:

Copy
Copied!
            

{ "execution_type":"async", "cmd": "show interfaces ethernet 1/2" }

JSON Query Requests

JSON Query requests are HTTPS GET requests that contain a job ID parameter. Using a query request, the user can get information on the current execution state of an ongoing request or the execution results of a completed request. To send a query request, the user should add the following parameters to the JSON URL.

Copy
Copied!
            

job_id=<job number>

Example:

Copy
Copied!
            

https://<gateway-ip-address>/admin/launch?script=json&job_id=<job number>

See “JSON Examples” for more examples.

Warning

Set commands normally do not return any data or output. If a set command does return an output, it will be displayed in the “status_message” field.

Single Command Response Format

The HTTPS POST response format structure is a JSON object consisting of 4 name-value pairs as follows:

Copy
Copied!
            

{ "executed_command": "<CLI command that was executed>", "status" = "<OK|ERROR>", "status_message" = "<information on the status received>", "data" = {the information that was asked for in the request} }

  • executed_command—the CLI command that was executed in the request

  • status—the result of the request execution:

    • “OK” if the execution is successful

    • “ERROR” in case of a problem with the execution

  • The value type of this key is “string”

  • data—a JSON object containing the information requested. Returns an empty string if there is no data.

  • status message—additional information on the received status. May be empty. The value type of this key is “string”.

Example:

Copy
Copied!
            

{ “executed_command”: “show interfaces ib 1/1 "status": "OK", "status_message": "", "data": { "speed": "HDR", "admin_state": "up" } }

See “JSON Examples” for more examples.

Multiple Command Response Format

The HTTPS response format structure is a JSON object consisting of a list of JSON results. Each JSON structure in the list is structured the same as in the single command execution response (see the previous section).

However, the status field can contain in this case an additional value, “ABORTED”, in case a previous command failed. This status value indicates that the command has not been executed at all in the system.

Copy
Copied!
            

{ "results": [ { "executed_command": "<…>", "status": "<OK|ERROR|ABORTED>", "status_message": "<…>", "data": {…} }, { "executed_command": "<…>", "status": "<OK|ERROR|ABORTED>", "status_message": "<…>", "data": {…} }, … { "executed_command": "<…>", "status": "<OK|ERROR|ABORTED>", "status_message": "<…>", "data": {…} } ] }

Example:

Copy
Copied!
            

{ "results": [ { "executed_command": "show interfaces ethernet 1/2", "status": "OK", "status_message": ""  "data": {"speed":"100GbE", "admin_state":"up"} }, { "executed_command": "show interfaces ethernet 1/100", "status": "ERROR", "status_message": "wrong interfaces name", "data": "" } ] }

See “JSON Examples” for more examples.

Query Response Format

Response to a query request can be of two types. In case the request completes its execution, the response will be similar to the single/multiple command response format, depending on the format of the request, and will display the execution results.
In case the execution is not complete yet, the response format will be similar to the single command response format. However, the status field will contain in this case the value “PENDING” to indicate that the request is still in progress. In addition, the “executed_command” field will contain the current request command being handled by the system.

Example:

Copy
Copied!
            

{ "executed_command": "show interfaces ethernet 1/2", "status": "PENDING", "status_message": "", "data":"" }

Asynchronous Response Format

Response to an asynchronous request is similar to the HTTPS response format of the single command response. However, an additional unique field will be added, “job_id”, containing the job id number for querying the request later. The value of the job_id key is of type string.

Another difference is that the “executed_command” field will be empty.

Example:

Copy
Copied!
            

{ "executed_command": "" "status": "OK" "status_message": "" "data": "" "job_id": "2754930426" }

  • Show commands

  • Set commands— all non-interactive CLI set commands are supported

    Warning

    Interactive commands are commands which require user interaction to complete (e.g., type “yes” to confirm). These commands are not supported by the JSON API.

The following examples use curl (a common tool in Linux systems) to send HTTPS POST requests to the system.

Synchronous Execution Request Example

Single Command

This example sends a request to query the system profile.

Request (save it to a file named req.json):

Copy
Copied!
            

{"cmd": "show inventory"}

Send the request:

Copy
Copied!
            

curl -b /tmp/cookie -X POST -d @req.json "https://10.10.10.10/admin/launch?script=json" 

When the system finishes processing the request, the user will receive a response similar to the following:

Copy
Copied!
            

{ "status": "OK", "executed_command": "show clock", "status_message": "", "data": { "Time": "07:47:53", "Date:": "2020/07/06", "Time zone": "UTC (Etc/UTC)", "UTC offset": "same as UTC" } }

Multiple Commands

This example sends a request to change an interface description and then queries for its status.

Request (save it to a file named req.json):

Copy
Copied!
            

{"commands": ["interfaces ethernet 1/2 description test description", "show clock"]}

Send the request:

Copy
Copied!
            

curl -b /tmp/cookie -X POST -d @req.json "https://10.10.10.10/admin/launch?script=json" 

When the system finishes processing the request, the user will receive a response similar to the following:

Copy
Copied!
            

{ "results": [ { "status": "OK", "executed_command": "interfaces ethernet 1/2 description test description", "status_message": "", "data": "" }, { "status": "OK", "executed_command": "show clock", "status_message": "", "data": { "Time": "07:47:53", "Date:": "2020/07/06", "Time zone": "UTC (Etc/UTC)", "UTC offset": "same as UTC" } ] }

Asynchronous Execution Request Example

This example sends an asynchronous request to change an interface description and then queries for its status.

Request (save it to a file named req.json):

Copy
Copied!
            

{"execution_type":"async", "commands": ["interfaces ethernet 1/2 description test description", "show clock"]}

Send the request:

Copy
Copied!
            

curl -b /tmp/cookie -X POST -d @req.json "https://10.10.10.10/admin/launch?script=json" 

The system immediately returns a response similar to the following:

Copy
Copied!
            

{ "executed_command": "", "status": "OK", "status_message": "", "data": "", "job_id": "91329386" }

Query Request Example

This example sends a request to query for a job ID received from a previous execution request.

The request is a an HTTPS GET operation to the JSON URL with the “job_id” parameter.

Send the request:

Copy
Copied!
            

curl -b /tmp/cookie -X GET "https://10.10.10.10/admin/launch?script=json&job_id=91329386" 

If the system is still processing the request, the user receives a response similar to the following:

Copy
Copied!
            

{ "executed_command": " interfaces ethernet 1/2 description test description ", "status": "PENDING", "status_message": "", "data": "" }


If the system is done processing the request, the user receives a response similar to the following:

Copy
Copied!
            

{ "results": [ { "status": "OK", "executed_command": "interfaces ethernet 1/2 description test description", "status_message": "", "data": "" }, { "status": "OK", "executed_command": "show clock", "status_message": "", "data": { "Time": "07:47:53", "Date:": "2020/07/06", "Time zone": "UTC (Etc/UTC)", "UTC offset": "same as UTC" } ] }

Error Response Example

General Error

This example sends a request with an illegal JSON structure.

Request—without closing bracket “]” (save it to a file named req.json):

Copy
Copied!
            

{"commands": ["interfaces ethernet 1/2 description test description", "show clock"}

Send the request:

Copy
Copied!
            

curl -b /tmp/cookie -X POST -d @req.json "https://10.10.10.10/admin/launch?script=json" 

Error response:

Copy
Copied!
            

{ "status": "ERROR", "executed_command": "", "status_message": "Handle request failed. Reason:\nIllegal JSON structure found in given JSON data.\nExpecting , delimiter: line 1 column 95 (char 94)", "data": "" }

Multiple Command Request Failure

This example sends a multiple command request where one command fails.

Request—with a non-existing interface (1/200) (save it to a file named req.json):

Copy
Copied!
            

{ "execution_type": "sync", "commands": [ "interfaces ethernet port-channel 1/2 mtu 1500", "interfaces ethernet port-channel 1/2 mtu 15000"] }

Send the request:

Copy
Copied!
            

curl -b /tmp/cookie -X POST -d @req.json "https://10.10.10.10/admin/launch?script=json" 

Error response:

Copy
Copied!
            

{ "results": [ { "status": "OK", "executed_command": "interfaces ethernet 1/2 mtu 1500", "status_message": "", "data": "" }, { "status": "ERROR", "executed_command": "interfaces ethernet 1/2 mtu 15000", "status_message": "% Value [15000] must be between 1500 and 9216", "data": "" } ] }

© Copyright 2023, NVIDIA. Last updated on May 23, 2023.