NSX REST API Overview

Automating the Software-Defined Network

Traditional networking models (i.e. hardware-defined networking) ties the network function layer to the physical device implementation.  In many ways, this is still a requirement, as data cannot transfer through thin air.  However, with the advent of software-defined networking, virtualized networking overlays have been introduced into the network fabric stack, allowing most network functions to be abstracted from the physical hardware into the logical space of a network.  This has the advantage of decoupling network changes from hardware changes and removes the need to manage physical devices in order to manage network configuration.

Traditionally, coordinating network device configuration changes was a patch work of manual procedures and automated tools, leading to many misconfigurations that can be hard to track down after being introduced to the network.  One of the most powerful thins about software-defined networking is the ability to establish a centralized control plane that can be programmatically controlled in order to produce configuration changes.

Once things are moved into a programmatic access and control paradigm, the agility of the entire network configuration and infrastructure is increased by orders of magnitude due to the ability to manage the end-to-end lifecycle completely in software with tools that operate quickly and consistently.

NSX REST API

Thankfully, NSX comes complete with a REST API that can be easily consumed from command line and scripting tools in addition to full-scale custom coding solutions.  This makes it accessible from other VMware technologies, such as vRealize Automation, and vRealize Orchestrator, as well as to PowerShell scripting and shell scripting (via curl, for example).  It is also possible to write custom code solutions that integrate NSX configuration modifications via the REST API into consistent workflows that accomplish work on behalf of system administrators and end users for the purposes of automatically, consistently, and securely configuring the network.

The NSX REST API follows a familiar model to other REST interfaces, requiring basic authentication over an SSL encrypted connection on port 443.

As of the current release (6.4), the NSX API only supports XML, except some experimental features support JSON responses.  All requests must include the Content-Type: application/xml header for the server to respond properly.

The main service URI base is /api/2.0/{endpoint}/method.  Thus, in order to make a REST call to get all virtual wires for a scope, you would make a GET request to https://nsx-manager-server/api/2.0/vdn/scopes/{scopeId}/virtualwires

API Endpoints

The following list of API endpoints are available for making calls to automate actions within NSX:

  • Distributed Virtual Switches - /api/2.0/vdn/switches – get information about vSphere distributed switches (NSX only supports distributed switches), or prepare them for NSX/VXLAN
  • Configuration - /api/2.0/vdn/config – manage configuration on segments/segement pools, multicast, VXLAN, and vSphere hosts
  • Transport Zones - /api/2.0/vdn/scopes – management of transport zones
  • Traceflow - /api/2.0/vdn/traceflow – management/configuration of Traceflow
  • Logical Switches - /api/2.0/vdn/virtualwires – create, read, update, delete (CRUD) operations of logical switches and connection of virtual machine
  • NSX Controllers - /api/2.0/vdn/controller – management of NSX controllers, including deployment, and removal
  • Services - /api/2.0/services (and /api/4.0/services) – manage applications, services, and service groups, including IPAM, security tags, SSO, users, roles, security groups, IP sets, vCenter configuration, task services, alarms, Spoof Guard, trust store and certificates, security policies, SNMP configuration, etc.
  • Universal Sync Configuration - /api/2.0/universalsync – manage universal sync configuration in cross vCenter configurations
  • Appliance Management - /api/1.0/appliance-management – NSX Manager appliance management and information
  • System Events - /api/2.0/systemevent – Get NSX Manager system events
  • Audit Logs - /api/2.0/auditlog – Get NSX Manager audit logs
  • VMware Customer Experience Improvement Program - /api/1.0/telemetry/config – Manage the Customer Experience Improvement Program membership
  • Network Fabric Configuration - /api/2.0/nwfabric – Configuration of clusters, hosts, VIB installation, and VXLAN configuration
  • Security Services - /api/2.0/si/ - Manage Guest Introspection, logical firewall, and external vendor components
  • Data Collection on a VM - /api/1.0/eventcontrol/vm/{vmID}/request – configure data collection on a virtual machines and globally
  • Guest Introspection and Endpoint Security - /api/2.0/endpointsecurity/ - manage endpoint security and registrations/activations of solutions.
  • Distributed Firewall - /api/4.0/firewall/ - manage the NSX distributed firewall (DFW)
  • Flow Monitoring - /api/2.1/app/flow/ - manage application flow monitoring settings
  • NSX Edges - /api/4.0/edges – Manage the creation, deletion, and configuration of NSX Edge appliances and distributed logical routers (DLRs)
  • NSX Edge Configuration Publishing - /api/4.0/edgePublish/ - manage aspects of NSX Edge Configuration publishing
  • NSX Manager CLI - /api/1.0/nsx/cli/ - execute NSX Manager CLI commands using the REST API
  • Hardware Gateways - /api/2.0/vdn/hardwaregateway/ - configuration settings relating to hardware gateways

Within each of these endpoints is a number of sub options and methods available for executing configuration actions against NSX.  These can be control plane or data plane actions and allow for the automation of just about every aspect of an NSX environment following initial deployment.

In a future article, we will cover example consumption of various NSX REST API endpoints.

Leave a comment