Using Postman with NMC API

Overview

Postman is a powerful tool for API development, testing, and quality assurance. It natively supports importing YAML-based APIs that adhere to the OpenAPI specification, such as the Nasuni NMC API.

Note: A known issue with Postman v7.2.2 - 7.6 prevented the Nasuni NMC API yml file from importing (github.com/postmanlabs/swagger2-postman2/issues/34). This was resolved in Postman v7.7. If you encounter an error importing the yml file, please update to the latest version of Postman.

A functioning Postman API test environment is invaluable for API script authors, providing insights into the Nasuni NMC API's operations, including required inputs and expected outputs. Postman also generates corresponding code for each query and offers ready-to-copy output for various API scripting environments.

Definitions

• YAML: A human-friendly data serialization standard for all programming languages.

• OpenAPI: The OpenAPI Specification (formerly known as Swagger Specification) is a format for describing REST APIs. An OpenAPI file describes the entire API, including available endpoints (e.g., /users), operations on each endpoint (e.g., GET /users, POST /users), and operation parameters (input and output for each operation).

• JSON: An open-standard file format that uses human-readable text to transmit data objects consisting of attribute-value pairs and array data types (or any other serializable value). JSON is widely used for asynchronous browser-server communication and has replaced XML in many AJAX-style systems.

Setup

Follow these steps to configure Postman, import the NMC API OpenAPI file to create a collection, and customize it for use with the NMC API.

Downloading the NMC API YAML file

1. On the NMC appliance, click Console Settings. The Console Settings page appears.

2. In the left column, click NMC API Keys. The NMC API Access Keys page appears.
   

3. At the bottom left, one or more links to the OpenAPI specification appear.
   

4. Click the NMC API version number to download. Several versions of the NMC OpenAPI specification are available:

   • 1.0.0 – Nasuni Edge Appliance version 7.10; supports GET actions

   • 1.1.0 – Nasuni Edge Appliance version 8.0 and higher; supports GET, POST, PATCH, and DELETE actions.

   • 1.2.0 -- Cloud credentials can be updated using APIs.

5. Save the downloaded YAML (.yml) file.

Downloading and configuring the Postman software

To download and configure the Postman software, follow these steps:

1. On your browser and go to https://www.postman.com/downloads/.

2. Download and install the appropriate version of Postman for your operating system.

3. Launch the Postman application.

4. Click Import and follow the instructions to import the NMC API YAML file you saved.

5. After importing, a new collection labeled "Nasuni Management Console API" appears on the left.

6. If your NMC does not have a trusted SSL certificate, enable self-signed SSL certificates in Settings —> General (or using the wrench icon at the top of the window) to prevent certificate errors.

7. Set up the Postman environment to include the required parameters for communication with your NMC instance. Use the “Quick Look” preview feature to display and edit your environment and global variables in one place. To toggle the display, either click the “eye” icon in the top right, or press Ctrl+Alt+E (Windows) or CMD+ALT+E (Mac).

8. If this is your first time using Postman, create a new environment:

   1. Click the + sign in the Environment section

   2. Enter the following details and click “Save”:

      1. Environment name

      2. A variable named "baseUrl" that includes the protocol, NMC hostname, and API version, such as:
         “https://nmc.company.com/api/v1.2”
         Enter the corresponding NMC hostname or IP address as the value. This value replaces “{{baseUrl}}” in requests.
         The completed add environment dialog should look like this:
         
         

9. Select the newly created NMC environment by clicking the Environments dropdown menu next to the Quick Look icon.
   

10. Under the Collection menu on the left, expand the "Nasuni Management Console API" section. Navigate to auth > login > POST Login and edit the Body by selecting the “raw” encoding option. Enter the following text replacing “MyUsername” and “MyPassword” with the corresponding values for the user with NMC API access.
    

{
      “username”: “MyUsername”,
      “password”: “MyPassword”
}

Note: The username for Active Directory accounts supports both UPN (user@domain.com) and DOMAIN (\\samaccountname) formats (two backslashes required):

The completed auth section of the UI should look like this:

Tip: Select “raw” for the body, not form-data or any other choice.

11. Add the following two lines to the Scripts > Post-response section of the Login endpoint:
    var data = pm.response.json();

    pm.environment.set("token", data.token);

12. The completed Tests section should now look like this:

    

13. Click Send. A token, along with a response, is returned at the bottom of the page when the request is successful, and a new entry named “token” is stored in the environment.
     

14. You can verify both the baseUrl and token variables are defined in your environment.
    

Using the NMC

The NMC API Access Keys page lists the issued API access keys for the requesting user and allows administrators to revoke API access keys.

Configuring API actions

After successfully requesting a token, you can begin performing API actions. The imported functions are ready to use but require additional configuration to include the appropriate elements for the environment and use the token for Authentication.

For each API action you want to use, follow these steps:

1. In the "GET/POST/UPDATE" Request Builder URL line, define variables for elements such as hostname, volume_guid, and filer_serial_number.

2. Define the associated environment variable using the Quick Look function mentioned above.

   Note: Postman sets the Auth Type to “Inherit auth from parent” by default.
   
   Authorization Key and Value pair when “Inherit auth from parent” is set:
    
    
   

3. Change the Auth Type to “No Auth”.
    

4. Add a key named Authorization with a value of “Token {{token}}”.
   The following example uses a GET request for the List volumes API request.

5. Run the request using the “Send” function.
   The following is an example output.
   

Note: API action elements prefixed with “POST” or “PATCH” require a body as part of the action. The full Nasuni NMC API documentation defines these requirements: http://docs.api.nasuni.com/.

Use the body section of the query to specify the corresponding elements for the action. The JSON formatted body returned for the associated “GET” action can serve as a source for the related “POST” or “UPDATE” action. For example, the body returned by the “GET Get share” action can be used as a starting point for the “POST Create share” action. Enter the desired value for the action you are performing for each JSON string.