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.
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:
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:
{
"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".
{
"username": "admin",
"password": "admin"
}
Run the following from the server’s shell to create a login session ID in the file: cookiejar.
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:
{
"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:
{
"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:
{
"username": "<user name>",
"password": "<user password>",
"commands | cmd": ["<cli command 1>", "<cli command 2>"] | "<cli command>",
"execution_type": "sync | async"
}
Example:
{
"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:
{
"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.
{
"status":"ERROR","status_message":" ‘admin’ password was already set & ‘monitor’ password was already set"}Admin and Monitor passwords were changed successfully.
{
"status_message":" <‘admin’ password was updated successfully> & <‘monitor’ password was updated successfully> "}Admin and Monitor passwords were not updated.
{
"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.
{
"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.
{
"status":"ERROR","status_message": “Please set thedefaultpasswordfor‘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.
Perform a POST operation on URL (the request should contain the session cookie).
[gateway_ip]/script=rh&template=json-request&action=json-logout
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).
{
"status":"OK","status_message":"Successfully logged-out"}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.
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:
{
"cmd":"<CLI command to execute>"}Example:
{
"cmd":"show interfaces ethernet 1/2"}Multiple command execution request format:
{
"commands":["<CLI cmd 1>","<CLI cmd 2>", … , <CLI cmd n>] }Example:
{
"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.
"execution_type":"<async|sync>"
Example:
{
"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.
job_id=<job number>
Example:
https://<gateway-ip-address>/admin/launch?script=json&job_id=<job number>
See “JSON Examples” for more examples.
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:
{
"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:
{
“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.
{
"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:
{
"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:
{
"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:
{
"executed_command": ""
"status": "OK"
"status_message": ""
"data": ""
"job_id": "2754930426"
}
Show commands
Set commands— a ll non-interactive CLI set commands are supported
NoteInteractive 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):
{"cmd": "show inventory"}
Send the request:
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:
{
"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):
{"commands": ["interfaces ethernet 1/2 description test description",
"show clock"]}
Send the request:
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:
{
"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):
{"execution_type":"async",
"commands": ["interfaces ethernet 1/2 description test description",
"show clock"]}
Send the request:
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:
{
"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:
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:
{
"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:
{
"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):
{"commands": ["interfaces ethernet 1/2 description test description",
"show clock"}
Send the request:
curl -b /tmp/cookie -X POST -d @req.json "https://10.10.10.10/admin/launch?script=json"
Error response:
{
"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):
{
"execution_type": "sync",
"commands": [ "interfaces ethernet port-channel 1/2 mtu 1500",
"interfaces ethernet port-channel 1/2 mtu 15000"]
}
Send the request:
curl -b /tmp/cookie -X POST -d @req.json "https://10.10.10.10/admin/launch?script=json"
Error response:
{
"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": ""
}
]
}