View Page online: https://www.sonicwall.

com/support/knowledge-base/introduction-to-sonicos-api/200818060121313/

Introduction to SonicOS API

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 for SonicOS 7.X

This release includes significant user interface changes and many new features that are different from the
SonicOS 6.5 and earlier firmware. The below resolution is for customers using SonicOS 7.X firmware.

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.3.

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

4.

5. Click on Accept6. .

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:

HTTP method Description

GET Retrieves the specified resource or collection of resources. GET is a
read-only operation that does not alter appliance state or
configuration. A GET operation should not contain a request body.
POST Submits data to be processed by the specified resource or collection
of resources. In most cases, the POST verb is used by SonicOS
APIs to create and add a resource to a collection of resources (for
example, add a new MAC address object to the collection of objects).
PUT Updates the specified resource. The data included in the PUT
request body replaces the previous configuration.
DELETE Deletes the specified resource or collection of resources.

Supported HTTP header request and response formats:

Type Example
Text/plain GET /api/sonicos/address-objects/macAccept: text/plain
Application/JS POST /api/sonicos/address-objects/macContent-type:
ON application/jsonAccept: application/json{"address_object": {"mac":
{"name": "001122334455","address": "001122334455","multi_homed":
true,"zone": "LAN"}}}

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:

CodeStatus Text Description

200 OK The request succeeded.

400 Bad Request Request An invalid request was submitted. Verify that the request
URI is correct and that the request body is as expected.
401 Not Authorized The user is unauthenticated or lacks the required privileges for
the operation requested.
403 Forbidden The request was understood by the server but denied. The
response body notes the reason why the request was denied.
404 Not Found The resource specified was not found.
405 Method Not The HTTP verb specified is not allowed or supported by the
Allowed resource specified.
406 Not The MIME type specified in the HTTP Content-type and/or
Acceptable Accept header is not supported.
413 Request body The maximum size of the request body was exceeded.
too large
414 Request URL The requested URL exceeded the maximum size allowed or
too long contains extra/unknown parameters (directories).
500 Internal Server The request failed due to an internal server error. The response
Error body should note the reason why the request failed.
503 No resources The maximum number of sessions was exceeded.

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:

Attribute Type Description

Attribute Type Description
status object Status object.
status.success boolean(true|fa Boolean success flag. Refer to the status.info
lse) array for more detailed information as to what
caused the error if the success flag is false.
status.cli object CLI status. Note: This attribute is included only
when an API sent one or more commands to the
CLI backend.
status.cli.depth number(uint8) Current mode depth of the CLI:• 0 = top level
mode• >= 1 config mode
status.cli.mode string Name of the current mode.
status.cli.comman string Command last executed.NOTE: This attribute is
d only included upon command error(s).
status.cli.configuri boolean(true|fa Boolean configuring flag. Should always be true
ng lse) upon one or more consecutive POST, PUT or
DELETE API calls that modify the configuration.
status.cli.pending_ boolean(true|fa Boolean pending config flag. Should always be
config lse) true upon one or more consecutive POST, PUT or
DELETE API calls that modify the configuration.
This flag should be cleared once any/all pending
changes are committed (saved).
status.cli.restart_r string Appliance restart status. To take effect, some
equired configuration changes require an appliance restart.
These values indicate the type of restart needed:•
NONE• APPLIANCE• CHASSIS•
CHASSIS_SHUTDOWN• ALL_BLADES
status.info array Informational message(s).
status.info.level string Status level: info, warning, error.
status.info.code string Status code. If success, E_OK is returned, else
E_{XXX} where XXX = error code.
status.info.messag string Status message.
e

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.

Resolution for SonicOS 6.5

This release includes significant user interface changes and many new features that are different from the
SonicOS 6.2 and earlier firmware. The below resolution is for customers using SonicOS 6.5 firmware.

SonicOS API is disabled by default in SonicOS. Any attempts to access SonicOS API while it is disabled
results in an HTTP 403 Forbidden error. To use the SonicOS API, you must enable it, either through the
SonicOS Management Interface or from the CLI.

From the GUI,

1. Navigate to MANAGE | Appliance | Base Settings2. and scroll down to SonicOS API 3. section.

4. Enable the option 'Enable SonicOS API' and 'Enable RFC-2617 HTTP Basic Access authentication'
option. Other advanced authentication mechanisms can also be enabled on the same page.5.

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

6.

7. Click on Accept8. .

From the CLI, Starting at the config# prompt:

config()# administration

(config-administration)# sonicos-api

(config-sonicos-api)# basic

(config-sonicos-api)# commit
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:

HTTP method Description

GET Retrieves the specified resource or collection of resources. GET is a
read-only operation that does not alter appliance state or
configuration. A GET operation should not contain a request body.
POST Submits data to be processed by the specified resource or collection
of resources. In most cases, the POST verb is used by SonicOS
APIs to create and add a resource to a collection of resources (for
example, add a new MAC address object to the collection of objects).
PUT Updates the specified resource. The data included in the PUT
request body replaces the previous configuration.
DELETE Deletes the specified resource or collection of resources.

Supported HTTP header request and response formats:

Type Example
Type Example
Text/plain GET /api/sonicos/address-objects/macAccept: text/plain
Application/JS POST /api/sonicos/address-objects/macContent-type:
ON application/jsonAccept: application/json{"address_object": {"mac":
{"name": "001122334455","address": "001122334455","multi_homed":
true,"zone": "LAN"}}}

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:

CodeStatus Text Description

200 OK The request succeeded.

400 Bad Request Request An invalid request was submitted. Verify that the request
URI is correct and that the request body is as expected.
CodeStatus Text Description

401 Not Authorized The user is unauthenticated or lacks the required privileges for
the operation requested.
403 Forbidden The request was understood by the server but denied. The
response body notes the reason why the request was denied.
404 Not Found The resource specified was not found.
405 Method Not The HTTP verb specified is not allowed or supported by the
Allowed resource specified.
406 Not The MIME type specified in the HTTP Content-type and/or
Acceptable Accept header is not supported.
413 Request body The maximum size of the request body was exceeded.
too large
414 Request URL The requested URL exceeded the maximum size allowed or
too long contains extra/unknown parameters (directories).
500 Internal Server The request failed due to an internal server error. The response
Error body should note the reason why the request failed.
503 No resources The maximum number of sessions was exceeded.

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:

Attribute Type Description

status object Status object.
status.success boolean(true|fa Boolean success flag. Refer to the status.info
lse) array for more detailed information as to what
caused the error if the success flag is false.
status.cli object CLI status. Note: This attribute is included only
when an API sent one or more commands to the
CLI backend.
status.cli.depth number(uint8) Current mode depth of the CLI:• 0 = top level
mode• >= 1 config mode
status.cli.mode string Name of the current mode.
Attribute Type Description
status.cli.comman string Command last executed.NOTE: This attribute is
d only included upon command error(s).
status.cli.configuri boolean(true|fa Boolean configuring flag. Should always be true
ng lse) upon one or more consecutive POST, PUT or
DELETE API calls that modify the configuration.
status.cli.pending_ boolean(true|fa Boolean pending config flag. Should always be
config lse) true upon one or more consecutive POST, PUT or
DELETE API calls that modify the configuration.
This flag should be cleared once any/all pending
changes are committed (saved).
status.cli.restart_r string Appliance restart status. To take effect, some
equired configuration changes require an appliance restart.
These values indicate the type of restart needed:•
NONE• APPLIANCE• CHASSIS•
CHASSIS_SHUTDOWN• ALL_BLADES
status.info array Informational message(s).
status.info.level string Status level: info, warning, error.
status.info.code string Status code. If success, E_OK is returned, else
E_{XXX} where XXX = error code.
status.info.messag string Status message.
e

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 MANAGE | API and click on the link https://SonicOS-api.sonicwall.com.
þÿSwagger will prepopulate your SonicWalls s IP, MGMT Port, Firmware so it can 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.

See also:

Adding Multiple Address Objects Using SonicOS API

Port Forwarding Configured Using SonicOS API

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