What is REST API?

if you are new to Rest API and wondering what exactly it is and what do we do using API, then I would recommend reading this article first before moving down further in this post. Also I found this article very useful to understand how Rest API works.

Before starting the topics of objective 8.1, I want to pen down few facts about Rest API.

• The NSX Manager accepts API requests on TCP port 443 over HTTP application protocol.
• You need a rest client to execute Rest API calls. There are plenty of clients available such as Postman and CURL (linux based). You can also integrate the Rest client in your browser. For mozilla firefox you can add this extension and for chrome you can add this
• Rest API’s are usually used when you can’t do something from GUI (because there is no option available) or when you want to automate stuffs using scripting or some other tools.
• The REST API utilises HTTP requests and allow you to programmatically create, retrieve, modify or delete NSX objects.
• You can use HTTP GET commands to read and retrieve objects, HTTP PUT or POST to create or update objects and HTTP DELETE to delete objects.

Construct and execute an API call using correct syntax and formatting

 

There are a couple of things which you need to construct an API request.

1: Basic Authentication: Credentials which the REST client will use to authenticate against NSX manager. This can be NSX admin user or any AD user.

2: Authorisation Header: For GET calls this is usually “Accept:application/xml”

3: API Endpoint URL: It’s hard to remember API URL for each type of operation and to get this you have to use NSX API Guide. 

Lets walk through these steps using Postman windows application. 

a: Launch Postman application and go to ‘Authorization’ tab and select “Basic Auth” from dropdown.

b: Specify NSX manager admin username/password or any other AD user which can authenticate against NSX.

c: Go to Headers tab and add a new key as shown below

Now to get API URL, you have to search in NSX API Guide. Below screenshot shows one example of querying a virtualwire.

Based on above info, my API endpoint will be https://NSXMGR-FQDN/api/2.0/vdn/virtualwires/{virtualwire-id}

Set the method to GET and paste your API endpoint URL and hit Send button.

if your syntax is correct, you will see an output

Now let’s fire up the same API call using curl from a linux box.

Note: While using curl for executing API calls, the output returned is not formatted and its hard to read the output. But you can append “| tidy -xml -indent -quiet” at the end of the URL to get a formatted xml. For this to work, you should have package tidy installed in your linux machine.

You can fire GET calls for other objects to get familiar with it.

Now let’s try to do a POST/PUT call. POST and PUT are used to configure or edit a setting on NSX manager. You need to pass a header ‘Content-Type:application/xml’ alongwith a custom xml which contains your configuration parameters.

Lets try to change the name of the virtualwire “App-Tier” to App-Tier-1. From the NSX API Guide, I obtained the custom xml which I needed to supply with PUT call

Here is my modified XML file as per my environment

Now to execute this API call via postman, open anew tab and add the NSX manager admin (or any other AD user) credential. Go to Headers tab and add a key “Content-Type:application/xml”

Go to Body tab and paste contents of your custom xml there.

Change method to PUT and paste the API endpoint URL and hit Send button.

If your API endpoint is correct and syntax of custom xml is correct, you will see a Status 200 OK at the bottom which means API was executed successfully. 

I verified by logging to Web Client that my virtualwire name was changed indeed.

Programmatically configure system parameters including:

NSX controller syslog

The only method available for configuring syslog on NSX controllers is via API. In vCenter Web Client, you will not get any such option under Networking & Security.

We need to do a POST call against NSX controllers to set the syslog. You can get the header and API Endpoint URL from NSX API Guide. In v6.3 of this guide, these instructions are on page 57. Here is what you need

Note: Controller ID can be either obtained by logging into Web Client and locating controllers.

Or via below REST API call

XML Body

To execute this API via curl, you need to first create a file on the linux machine from where you will invoke curl. The contents of this file will be

Note: You need to change the IP address as per your environment.

once you have created the file, you can execute the API call as shown below

On firing above API call, you should see a HTTP 200 OK in output. You can fire a GET call against the same controller to verify syslog settings has been updated. 

Modify DLR declared dead time

Declare dead time refers to configuring HA on DLR edge vm’s. By default the dead time is 15 seconds, which means if you have configured HA on DLR and if Active VM goes down, then within 15 seconds, failover will start and the secondary VM will become Active.

First we have to find out Edge ID of the DLR VM. Again this can be fetched from Web Client as well as API. Let me show you API method. You need to execute a GET call as shown below

# curl -sik -u ‘admin’ -H ‘Accept:application/xml’ -X GET https://nsxmgr-01a.corp.local/api/4.0/edges | tidy -xml -indent -quiet

You will get following output. Just search for <objectId>.

So Edge-ID of my DLR is edge-30. Lets check the HA configuration of this edge by executing below API

# curl -sik -u ‘admin’ -H ‘Accept:application/xml’ -X GET https://nsxmgr-01a.corp.local/api/4.0/edges/edge-30/highavailability/config | tidy -xml -indent -quiet
Enter host password for user ‘admin’:

As you can see in above output that HA is not configured on DLR. Also DeadTime is set to 15 secs. Suppose you have been tasked to change this to 30 seconds, you can execute below API call

XML Body

<highAvailability>
<declareDeadTime>30</declareDeadTime>
</highAvailability>

Curl command for the same can be as shown below.

where I put my XML body in file edge-ha.xml

on executing above API call, I saw following events happening in vCenter

I executed a GET call to verify dead time has been updated or not and it was updated.

# curl -sik -u ‘admin’ -H ‘Accept:application/xml’ -X GET https://nsxmgr-01a.corp.local/api/4.0/edges/edge-30/highavailability/config | tidy -xml -indent -quiet | grep declareDeadTime

Enter host password for user ‘admin’:

<declareDeadTime>30</declareDeadTime>

Analyze, modify, and successfully retrieve configuration data using an existing API call

 

This topic in blueprint don’t mentions any specific configuration data that needs to be reviewed/modified using API calls. You can refer to above examples to see how to perform a GET/POST API calls for pulling up needed data.

That’s it for this post. 

If you are new to NSX API, then I would recommend practicing it first in your lab before using it in production. Get yourself comfortable with API first and then explore its awesomeness. I have written several posts on using NSX API. Feel free to read them from below links.

Configure HA on NSX Edge via REST API

Upgrading NSX Manager using REST API

Retrieving NSX Manager System Info Using Rest API

Managing NSX Manager Network Settings via Rest API

NSX Certificate Management Using Rest API

I hope you enjoyed reading this post. Feel free to share this on social media if it is worth sharing. Be sociable