Using the NSX-T API

I've been writing some PowerShell scripts to automate NSX-T configuration lately, so I figured that I should put together a primer with notes about how to get started!  Firstly, if you're working with the API, you're going to want to be able to reference the official documentation.  There's a lot that can be done via the API, and that guide will tell you what calls to make to do most of it!  If you're like me and haven't spent a lot of time working with APIs before, that document will present a pretty steep learning curve... so I'm writing out my notes here, to make it easier for people to get started!

At its most basic, using the API is just sending a web request to the NSX-T manager and then reading the response.  Since this is potentially sensitive information, you're going to have to authenticate with the server though, so you'll need to include a Header with that login information.  If you want to change anything, you're also going to need to submit a Body with those new settings.  So, let's look at how we can do this with PowerShell!

First, we need to prepare the Header.  There are a few ways to authenticate with NSX-T, but the easiest is with Basic authentication (go figure).  In order to use this authentication method, you need to Base64 encode the username and password with a colon between them, then put it in your request Header as the "authorization" tag preceded by the word "Basic" and a space.  That sounds complicated, but it's a lot clearer when you can see how I do it:

$base64Creds = [Convert]::toBase64String([System.Text.Encoding]::UTF8.GetBytes('admin:mypass'))

$header = @{Authorization = "Basic $base64Creds"}

Those lines will generate headers to authenticate the user account "admin" with the password "mypass".  Of course, we don't really want to hard-code credentials into a script, so you'll probably want to do something like this to get them as a secure PowerShell object:

if (!($creds)){

$creds = Get-Credential -Message "NSX-T Administrative Credentials:"

}

$base64Creds = [Convert]::toBase64String([System.Text.Encoding]::UTF8.GetBytes("$($creds.username):$($creds.GetNetworkCredential().password)"))

I like to write my scripts to accept a -creds input parameter (which would be a PSSecureCredential object, either entered during runtime or imported from an encrypted file on the hard drive).  If it's not there, then I prompt the user for the required credentials.

Once you've used your Base64 credentials and have made your header, you can begin querying NSX-T!  That should be all it takes to do just about any of the API calls that start with GET, so let's look at DHCP Server configurations as an example.  The documentation tells you that the URI path that you need to use is "/policy/api/v1/infra/dhcp-server-configs" but how do you actually use it?  Like this!

$uri = "https://my-nsx-t-server"

$results = invoke-webrequest -uri "$uri/policy/api/v1/infra/dhcp-server-configs" -headers $header

($results.content | convertfrom-json).results

So, you basically need to prepend the URI Path with the protocol and name of your NSX-T management server.  When you're looking through that document, you'll notice that there are two different APIs in NSX-T, some that start with /policy/api... and others that are just /api.  As a rule of thumb, use the /policy/api... versions whenever possible, as that's the API version that everything is being migrated to (and the other will eventually be retired).

That last line simply reads the results and displays them as a PowerShell object, which makes them easier to read and work with!

The last thing that I want to look at today is how we would make a change, so let's make a DHCP server.  Our last API call used the GET method (which is invoke-webrequest's default method); this one is going to need to use the PATCH method.  Frequently, APIs will use the PUT method for this situation, but the NSX-T API seems to like the PATCH method and I've had much better results when using it.

Once again, we're going to want to start with the API Documentation, to figure out what we're doing.  We're going to need 2 more things to make this work; a more detailed Header that'll tell NSX-T what kind of data to expect from us, and a Body that actually contains that data.  The new Header is pretty simple:

$headersPatch = @{Authorization = "Basic $base64Creds";'Content-type' = "application/json"}

This'll be extremely similar to our original Headers, except now we're adding that "Content-type" attribute to tell NSX that we're going to give it some JSON data.  Next, we'll need to build our Body, and fortunately, there's a great example in the documentation:

$body = '{

  "server_address": "10.1.1.1/30",

  "lease_time": 10000

}'

That's a very simple body that'll define a DHCP server with an address of 10.1.1.1 that uses 10,000 second leases.  If you expand the "request body" section of the API documentation, you'll be able to find all of the other attributes that you can specify here.  You can get very specific, if you're so inclined!  Once you've got your Body built, it's time to make the actual API call:

$results = invoke-webrequest -uri "$uri/policy/api/v1/infra/dhcp-server-configs/My-DHCP-Server" -headers $headersPatch -method patch -body $body

Notice that my URI has "My-DHCP-Server" at the end of the path; that's the ID of the new DHCP server configuration and it should not already exist.  Change it to be whatever's appropriate for your use case!

And there you have it, those are the basics for using PowerShell to access the NSX-T API!