Introduction to SonicOS API on NSSP 13700

07/12/2021 0 1339

DESCRIPTION:

SonicOS API provides an alternative to the SonicOS Command Line Interface (CLI) for configuring various functions.
SonicOS API is enabled by default in SonicOS 7.0 and SonicOSX where as disabled on SonicOS.
This KB explains how SonicOS API can be enabled, Supported Request Methods, Supported HTTP Headers, Supported HTTP MIME Types, Status and Error Representation, Client authentication, List of applicable APIs and various tools that can be used to make these API Calls.

RESOLUTION:

SonicOS API is enabled by default in SonicOS 7.0 and SonicOSX. The required authentication method can be selected from the interface.
From the GUI, 

1. Navigate to Device | Settings | Administration | Audit/SonicOS API
2. Click on the toggle switch for CHAP authentication or RFC-2617 HTTP Basic Access authentication. Other advanced authentication mechanisms can also be enabled on the same page.
   

    NOTE: The client would need to be set appropriately to authenticate based on this setting.

3. Click on Accept.
   

Supported Request Methods:

SonicOS API utilizes four of the methods defined in the HTTP protocol (RFC 7231 and RFC 5789) to create, read, update, and delete (CRUD) resources.

Supported HTTP request methods:

Supported HTTP header request and response formats:

Supported HTTP headers:

1. Content type: Specifies the format (MIME type) of the request body (input).
2. Accept: Specifies the format of the response body (output).

Supported HTTP MIME Types:
SonicOS supports these HTTP MIME types:

• Text/plain
• Application/JSON

These HTTP headers define the request and response format:

• Content‐type – Specifies the format (MIME type) of the request body (input)
• Accept – Specifies the format of the response body (output)

Status and Error Representation:

All plain text output from the last backend CLI command executed is captured and returned back to the client. If the command executed was not a show command and the requested operation succeeded, then the response body is empty. This is consistent with the CLI when executing a command via SSH or the serial console in that status is only rendered to the console upon error.
A JSON status object is guaranteed to be returned in the response body when performing a POST, PUT, or DELETE operation or upon error(s) encountered when processing a request.

HTTP Status Codes:

Application/JSON Schema structure and Attributes:

Schema Structure:

{
"status": {
"success": {boolean}
,"cli": {
"depth": {number}
,"mode": "{string}"
,"command": "{string}"
,"configuring": {boolean}
,"pending_config": {boolean}
,"restart_required": "{string}"
}
,"info": [
{ "level": "{string}", "code": "{string}", "message": "{string}" }
...
]
}
}

Schema Attributes:

Client Authentication:

SonicOS API offers the following mechanisms for client authentication:

• HTTP Basic Authentication (RFC 2617)
• Challenge‐Handshake Authentication (CHAP)
• Public Key authentication
• Session security using RFC-7616 Digest authentication
• Two-Factor and Bearer Token Authentication

Regardless of the authentication mechanism used, only:

• A single administrator can manage (modify configuration) at any given time. This remains true regardless of where an admin logged in (web management UI, CLI, GMS, or SonicOS API).
• Users with full admin privileges are allowed to access SonicOS API.
• A single SonicOS API session is currently allowed.

List of applicable APIs:

From the GUI, navigate to Home | API and click on the link https://SonicOS-api.sonicwall.com. Swagger will prepopulate it to give you a list of applicable APIs.

Tools that can be used to make API calls:

The following can be used on Windows or MAC devices:

1. Postman
2. Insomnia
3. Git Bash
4. Swagger

For Linux platforms, Curl can be used which is available by default.

EXAMPLE: You wish to migrate FQDN address objects from a Gen 6 to a Gen 7 device. SonicOS API can be very helpful and easy to achieve this requirement. Please take a look at the below link for more details.

How To Migrate FQDN Address Objects From A Gen 6 To Gen 7 Device Using SonicOS API?