Main Menu
  • COMPANY
    • Boundless Cybersecurity
    • Press Releases
    • News
    • Events
    • Awards
    • Leadership
    • Press Kit
    • Careers
  • PROMOTIONS
    • SonicWall Promotions
    • Customer Loyalty Program
  • MANAGED SERVICES
    • Managed Security Services
    • Security as a Service
    • Professional Services
SonicWall
  • Products
      All Products A–Z
      Free Trials
    • Network Security
      • Next-Generation Firewall (NGFW)
      • Network Security Services
      • Network Security Management
      • Secure SD-WAN
    • Threat Protection
      • Advanced Threat Protection Cloud
      • Advanced Threat Protection Appliance
      • Capture Labs
    • Secure Access Service Edge (SASE)
      • Zero-Trust Network Access (ZTNA)
    • Cloud Security
      • Cloud Firewall
      • Cloud App Security
    • Endpoint Security
      • Endpoint Detection & Response (EDR)
    • Email Security
      • Cloud Email Security
      • Hosted Email Security
      • On-Prem Email Security
    • Secure Access
      • Wireless Access Points
      • Network Switch
      • Virtual Private Network (VPN)
    • Wi-Fi 6 Access Points

      SonicWall SonicWave 600 series access points provide always-on, always-secure connectivity for complex, multi-device environments.

      Read More
  • Solutions
    • Industries
      • Distributed Enterprises
      • Retail & Hospitality
      • K-12 Education
      • Higher Education
      • State & Local
      • Federal
      • Healthcare
      • Financial Services
      • Carriers
    • Use Cases
      • Secure SD-Branch
      • Network Segmentation
      • Zero Trust Security
      • Secure SD-WAN
      • Office 365 Security
      • SaaS Security
      • Secure Wi-Fi
    • Solutions Widgets
      • Solutions Content Widgets
        Federal

        Protect Federal Agencies and Networks with scalable, purpose-built cybersecurity solutions

      • Solutions Image Widgets
  • Partners
    • SonicWall Partners
      • Partners Overview
      • Find a Partner
      • Authorized Distributors
      • Technology Partners
    • Partner Resources
      • Become a Partner
      • SonicWall University
      • Training & Certification
    • Partner Widgets
      • Custom HTML : Partners Content WIdgets
        Partner Portal

        Access to deal registration, MDF, sales and marketing tools, training and more

      • Partners Image Widgets
  • Support
    • Support
      • Support Portal
      • Knowledge Base
      • Technical Documentation
      • Community
      • Video Tutorials
      • Product Life Cycle Tables
      • Partner Enabled Services
      • Contact Support
    • Resources
      • Resource Center
      • Events
      • Free Trials
      • Blog
      • SonicWall University
      • MySonicWall
    • Capture Labs
      • Capture Labs
      • Security Center
      • Security News
      • PSIRT
      • Application Catalog
    • Support Widget
      • Custom HTML : Support Content WIdgets
        Support Portal

        Find answers to your questions by searching across our knowledge base, community, technical documentation and video tutorials

      • Support Image Widgets
  • COMPANY
    • Boundless Cybersecurity
    • Press Releases
    • News
    • Events
    • Awards
    • Leadership
    • Press Kit
    • Careers
  • PROMOTIONS
    • SonicWall Promotions
    • Customer Loyalty Program
  • MANAGED SERVICES
    • Managed Security Services
    • Security as a Service
    • Professional Services
  • Contact Sales
  • English English English en
  • BLOG
  • CONTACT SALES
  • FREE TRIALS
  • English English English en
SonicWall
  • Products
      All Products A–Z
      Free Trials
    • Network Security
      • Next-Generation Firewall (NGFW)
      • Network Security Services
      • Network Security Management
      • Secure SD-WAN
    • Threat Protection
      • Advanced Threat Protection Cloud
      • Advanced Threat Protection Appliance
      • Capture Labs
    • Secure Access Service Edge (SASE)
      • Zero-Trust Network Access (ZTNA)
    • Cloud Security
      • Cloud Firewall
      • Cloud App Security
    • Endpoint Security
      • Endpoint Detection & Response (EDR)
    • Email Security
      • Cloud Email Security
      • Hosted Email Security
      • On-Prem Email Security
    • Secure Access
      • Wireless Access Points
      • Network Switch
      • Virtual Private Network (VPN)
    • Wi-Fi 6 Access Points

      SonicWall SonicWave 600 series access points provide always-on, always-secure connectivity for complex, multi-device environments.

      Read More
  • Solutions
    • Industries
      • Distributed Enterprises
      • Retail & Hospitality
      • K-12 Education
      • Higher Education
      • State & Local
      • Federal
      • Healthcare
      • Financial Services
      • Carriers
    • Use Cases
      • Secure SD-Branch
      • Network Segmentation
      • Zero Trust Security
      • Secure SD-WAN
      • Office 365 Security
      • SaaS Security
      • Secure Wi-Fi
    • Solutions Widgets
      • Solutions Content Widgets
        Federal

        Protect Federal Agencies and Networks with scalable, purpose-built cybersecurity solutions

      • Solutions Image Widgets
  • Partners
    • SonicWall Partners
      • Partners Overview
      • Find a Partner
      • Authorized Distributors
      • Technology Partners
    • Partner Resources
      • Become a Partner
      • SonicWall University
      • Training & Certification
    • Partner Widgets
      • Custom HTML : Partners Content WIdgets
        Partner Portal

        Access to deal registration, MDF, sales and marketing tools, training and more

      • Partners Image Widgets
  • Support
    • Support
      • Support Portal
      • Knowledge Base
      • Technical Documentation
      • Community
      • Video Tutorials
      • Product Life Cycle Tables
      • Partner Enabled Services
      • Contact Support
    • Resources
      • Resource Center
      • Events
      • Free Trials
      • Blog
      • SonicWall University
      • MySonicWall
    • Capture Labs
      • Capture Labs
      • Security Center
      • Security News
      • PSIRT
      • Application Catalog
    • Support Widget
      • Custom HTML : Support Content WIdgets
        Support Portal

        Find answers to your questions by searching across our knowledge base, community, technical documentation and video tutorials

      • Support Image Widgets
  • COMPANY
    • Boundless Cybersecurity
    • Press Releases
    • News
    • Events
    • Awards
    • Leadership
    • Press Kit
    • Careers
  • PROMOTIONS
    • SonicWall Promotions
    • Customer Loyalty Program
  • MANAGED SERVICES
    • Managed Security Services
    • Security as a Service
    • Professional Services
  • Contact Sales
  • Menu

Introduction to SonicOS API on NSSP 13700

07/12/2021 1 People found this article helpful 185,940 Views

    Download
    Print
    Share
    • LinkedIn
    • Twitter
    • Facebook
    • Email
    • Copy URL The link has been copied to clipboard

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

    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 methodDescription
    GETRetrieves 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.
    POSTSubmits 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).
    PUTUpdates the specified resource. The data included in the PUT request body replaces the previous configuration.
    DELETEDeletes the specified resource or collection of resources.


    Supported HTTP header request and response formats:

    TypeExample
    Text/plainGET /api/sonicos/address-objects/mac
    Accept: text/plain
    Application/JSONPOST /api/sonicos/address-objects/mac
    Content-type: application/json
    Accept: 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 TextDescription
    200OKThe request succeeded.
    400Bad RequestRequest An invalid request was submitted. Verify that the request URI is correct and that the request body is as expected.
    401Not AuthorizedThe user is unauthenticated or lacks the required privileges for the operation requested.
    403ForbiddenThe request was understood by the server but denied. The response body notes the reason why the request was denied.
    404Not FoundThe resource specified was not found.
    405Method Not AllowedThe HTTP verb specified is not allowed or supported by the resource specified.
    406Not AcceptableThe MIME type specified in the HTTP Content-type and/or Accept header is not supported.
    413Request body too largeThe maximum size of the request body was exceeded.
    414Request URL too longThe requested URL exceeded the maximum size allowed or contains extra/unknown parameters (directories).
    500Internal Server ErrorThe request failed due to an internal server error. The response body should note the reason why the request failed.
    503No resourcesThe 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:

    AttributeTypeDescription
    statusobjectStatus object.
    status.successboolean
    (true|false)
    Boolean success flag. Refer to the status.info array for more detailed information as to what caused the error if the success flag is false.
    status.cliobject

    CLI status.

    Note: This attribute is included only when an API sent one or more commands to the CLI backend.

    status.cli.depthnumber
    (uint8)
    Current mode depth of the CLI:
    • 0 = top‐level mode
    • >= 1 config mode
    status.cli.modestringName of the current mode.
    status.cli.commandstringCommand last executed.
    NOTE: This attribute is only included upon command error(s).
    status.cli.configuringboolean
    (true|false)
    Boolean configuring flag. Should always be true upon one or more consecutive POST, PUT or DELETE API calls that modify the configuration.
    status.cli.pending_configboolean
    (true|false)
    Boolean pending config flag. Should always be 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_requiredstringAppliance restart status. To take effect, some configuration changes require an appliance restart. These values indicate the type of restart needed:
    • NONE
    • APPLIANCE
    • CHASSIS
    • CHASSIS_SHUTDOWN
    • ALL_BLADES
    status.infoarrayInformational message(s).
    status.info.levelstringStatus level: info, warning, error.
    status.info.codestringStatus code. If success, E_OK is returned, else E_{XXX} where XXX = error code.
    status.info.messagestringStatus message.


    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.

    Image

    Image

    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?

    Related Articles

    • Bandwidth usage and tracking in SonicWall
    • How to force an update of the Security Services Signatures from the Firewall GUI
    • Configure Guest VLAN in the TZ firewall, for guest users to access Internet only.

    Categories

    • Firewalls > NSsp Series > Firewall Management

    Not Finding Your Answers?

    ASK THE COMMUNITY

    Was This Article Helpful?

    YESNO

    Article Helpful Form

    Article Not Helpful Form

    Company
    • Careers
    • News
    • Leadership
    • Awards
    • Press Kit
    • Contact Us
    Popular resources
    • Communities
    • Blog
    • SonicWall Capture Labs

    Stay In Touch

    • By submitting this form, you agree to our Terms of Use and acknowledge our Privacy Statement. You can unsubscribe at any time from the Preference Center.
    • This field is for validation purposes and should be left unchanged.
    • Facebook
    • Twitter
    • Linkedin
    • Youtube
    • Instagram

    © 2023 SonicWall. All Rights Reserved.

    • Legal
    • Privacy
    • English
    Scroll to top