Networking NVIDIA UFM Enterprise REST API Guide

REST API Complementary Information

This section provides complementary information about all UFM REST APIs.

Exposing site_name Field in REST API

In addition to the existing REST API, you can configure UFM to expose the site_name field in all supported REST APIs. The value of the site_name field is configurable. The field identifies the InfiniBand fabric that UFM Enterprise manages.

To expose the site_name field, do the following:

  1. In the [Server] section of gv.cfg, set a value for site_name.

  2. In the [Server] section of gv.cfg, set expose_site_name to true.

  3. Restart UFM for the changes to take effect.

REST API for UFM Prime Deployment

To scope a request to a specific subnet or site, include the site name in the request filters using the site_name attribute.

Example of Regular Request

GET /ufmRest/resources/systems?type=switch

Example of UFM Prime Request Filtered by Site

GET /ufmRest/resources/systems?type=switch&site_name=site-a

When you use pagination or filter syntax, you can also include site_name as a filter:

GET /ufmRest/resources/systems?rpp=50&page_number=1&filter=site_name[eq]site-a

GET /ufmRest/resources/ports?rpp=50&page_number=1&filter=site_name[eq]site-a

GET /ufmRest/resources/modules?rpp=50&page_number=1&filter=site_name[eq]site-a

If no site_name is provided in multisubnet mode, the consumer returns objects from all provider sites. If site_name is provided, only objects that belong to that site are returned.

The response is also different in multisubnet mode. Model objects include a site_name field so the client can identify which provider site each object came from. For systems, ports, and modules, site_name contains the owning site name. For objects shared across multiple sites, such as multisite routers, site_name can contain multiple site names as a comma-separated value.

Example of Regular Response

[
  {
    "system_name": "switch-1",
    "guid": "0x0002c90300000001",
    "type": "Switch"
  }
]


Example UFM Prime Response

[
  {
    "system_name": "switch-1",
    "guid": "0x0002c90300000001",
    "type": "Switch",
    "site_name": "site-a"
  },
  {
    "system_name": "router-1",
    "guid": "0x0002c90300000002",
    "type": "Router",
    "site_name": "site-a,site-b"
  }
]

Example for Ports and Modules

[
  {
    "name": "0x0002c90300000001_1",
    "system_guid": "0x0002c90300000001",
    "logical_state": "Active",
    "site_name": "site-a"
  }
]


Regular REST API responses describe objects from one UFM fabric. UFM Prime REST API responses describe an aggregated fabric and add site_name, so you can filter each object by its provider site and trace it back to that site.

Examples of REST APIs Using Various Authentication Types

Basic Authentication

For basic authentication, run:

curl -k https://<ufm-ip>/ufmRest/resources/systems -u <username>:<password>

Session-based Authentication

To use session-based authentication, follow these steps:

  1. Run the following command to sign in and store the session in a cookie file:

    curl -k -f -X POST -c cookies.txt -d "httpd_username=<user>" -d "httpd_password=<password>" https://<ufm-ip>/dologin
    
  2. Use the saved session to make as many ufmRestV2 requests as needed. For example:

    curl -k –cookie cookies.txt https://<ufm-ip>/ufmRestV2/reources/systems
    
:note:

Session-Based REST API Authentication After Restart or Upgrade

When UFM Authentication Server is disabled, restarting or upgrading UFM invalidates existing Apache session cookies. The UFM GUI automatically removes the stale cookie before login, but REST API clients using session-based authentication must recover explicitly.

If the client receives authentication redirects or errors, or Apache logs AH01842, it must:

  1. Delete the session cookie from its cookie jar, or call GET /logout.

  2. Authenticate again through POST /dologin.

  3. Store and use the newly issued session cookie.

Clients using per-request Basic authentication are not affected.

Token-based Authentication

To use token-based authentication, follow these steps:

  1. Create an access token using either your credentials or your session:

    curl -k -X POST https://<ufm-ip>/ufmRest/app/tokens -u username:password
    
  2. Send requests to ufmRestV3 with the access token you generated:

    curl -k https://<ufm-ip>/ufmRest/resources/systems -H "Authorization:Basic <access_token>"
    

LDAP-based Authentication

To authenticate through the LDAP server that you configured, run:

curl -k https://<ufm-ip>/ufmRest/resources/systems -u <ldap-username>:<ldap-password>

For more information, see UFM Enterprise User Manual > Manage Users > Authentication Methods > LDAP Authentication.


Last updated: