Getting Started with the NSX-T API and Postman

Wether you like it or not, the API plays a significant role when installing, configuring, and managing an NSX-T environment. Sooner or later you will be facing tasks that either require you to use the API or simply are much faster to complete using the API.

Luckily, with the right tools and some preparation, getting started with API-based management isn’t all that hard.

In this article I will show you how I set up REST API Client Postman for interaction with the NSX-T API.

Step 1 – Download and install Postman

A pretty obvious first step. We need to download and install Postman. Get it from https://www.getpostman.com/.

Step 2 – Create a Postman environment

After we’ve installed Postman, we should create a Postman environment for our NSX-T environment.

An environment in Postman is a place where you create and store variables with their values. These can then be used within API requests. Using environment variables is a real time saver.

To create an environment in Postman choose File > New and select Environment.

Give the environment a name and add the following variables:

VariableValue
baseUrlyour-nsx-manager-fqdn
nsx-manager-useryour-nsx-manager-user
nsx-manager-passwordyour-nsx-manager-password

In Postman:

Step 3 – Download the NSX-T OpenAPI specifications

Both the Manager API and the Policy API are described in the OpenAPI format. You can download their specifications using a GET request.

The Manager API specification can be fetched at:

https://{{baseUrl}}/api/v1/spec/openapi/nsx_api.json

The Policy API specification is at:

https://{{baseUrl}}/policy/api/v1/spec/openapi/nsx_policy_api.json

We immediately make use of the “baseUrl” environment variable. Don’t forget to select the environment (in the top right corner) so that Postman knows where to fetch it’s value.

We also need to authenticate when connecting to the NSX-T API. This is configured under “Authorization“. Select “Basic Auth” from the “Type” list.
Instead of entering the NSX-T credentials in the Username and Password fields, you type a “{” and select the “nsx-manager-user” variable from the list that pops up:

Tick the “Show Password” box and then repeat this “trick”, but now select the “nsx-manager-password” variable instead:

Click the Send button to fetch the OpenAPI specifications.

Step 4 – Import the NSX-T OpenAPI specifications

The specifications are downloaded and available in the body of the GET requests:

Copy the contents of the request body by clicking on the two overlapping squares icon in the right corner and wait until it says “Copied to clipboard“:

Next, click the “Import” button in the upper left corner of the Postman application window and select “Paste Raw Text“. Paste the contents of the request body into the text box and then click the “Import” button:

In the dialog that pops up make sure that you only select “Generate a Postman Collection” and click “Next“:

After a couple of seconds you should see a new collection in Postman. For the Manager API the collection is called “NSX-T Manager API” and for the Policy API the collection is called “NSX-T Data Center Policy API“:

Step 5 – Configure Authorization

We also want all of the API requests in the collections to perform basic auth using the “nsx-manager-user” and “nsx-manager-password” variables that we defined in the Postman environment. This is configured at the collection level.

For each collection right-click and select “Edit“:

Click the “Autorization” tab and select “Basic Auth” from the “Type” list. Enter “{{nsx-manager-user}}” for “Username” and “{{nsx-manager-password}}” for “Password“. Click the “Update” button to save the changes:

The requests within the collections will now use these “parent” authorization settings.

Conclusion

It takes some minutes, but now that everything has been set up it will be less of a hassle to get started.

Who knows, next time when you need to configure or deploy something in NSX-T you might be doing it using one of the NSX-T API requests in Postman. 😉

6 Comments

  1. Dennis Jurgensen
    Permalink

    When I tried this with our NSX-T manager, Post was unable to import it collection. It seemed to have a problem with swagger 2.0. I’ve opened up a bug report against Postman, just wanted to let people know.

    Like

    Reply
    • rutgerblom
      Permalink

      Hi Dennis and thank you for bringing this to my attention. I’ve updated the post with a workaround.

      Rutger

      Like

      Reply
      • vpackets
        Permalink

        That is awesome Rutger ! I ll blog about what you have done ! make so much easy ! Wondering why VMware is not going 100% compliant here

        Like

  2. Ed McGuigan
    Permalink

    Hi Rutger:

    Well you taught me something there. I created a collection but was adding to it manually having no idea what swagger and API specifications were about. I am going to try import the API specification.

    I also authenticate to vIDM and so the authentication header has to be created in a more complex way with a base64 encoding of username and password prefixed with “Remote “. I ended up writing a Javascript function to generate it prior to the request being sent.

    pm.environment.set(“autheader”,”Remote “.concat(btoa(pm.environment.get(“pwd”))));

    pwd is actually a string like “user@domain:password”

    Finally, once I have done that authentication on an initial request, I use a combination of a JSESSIONID cookie and an X-XSRF-TOKEN received in this first response in subsequent requests and don’t send the Authorization header any more. In my mind, I am using an established session and not taxing the system with authentication/authorization of subsequent requests. I am not really sure if they added complication is worth it.

    Thanks again,

    Ed.

    Like

    Reply

Leave a Reply to Dennis Jurgensen Cancel reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.