REST API Complementary Information

The section provides complementary information with regard to all UFM REST APIs.

Exposing `site_name` Field in REST API

In addition to the existing REST API, users can configure the UFM to expose the site_name (configurable) field in all the supported REST APIs. The site_name field can be used to identify the current InfiniBand fabric that is managed by the UFM Enterprise.

To expose the site_name field, perform the following:

In gv.cfg and in the [Server] section, set a value for "site_name"
In gv.cfg and in the [Server] section, set "expose_site_name" to "true"
Restart UFM for the changes to take effect

REST API for UFM Prime Deployment

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

Example, regular request:

GET /ufmRest/resources/systems?type=switch

Example, UFM Prime request filtered by site:

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

When pagination/filter syntax is used, site_name can also be included 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"
  }
]

In short: regular REST API responses describe objects from one UFM fabric, while UFM Prime REST API responses describe an aggregated fabric and add site_name so each object can be filtered by, and traced back to, its provider 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

For session-based Authentication, follow the below instructions:

Run the below command to log 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

Use the session saved earlier to make as many ufmRestV2 requests as needed, for instance:
```
curl -k –cookie cookies.txt https://<ufm-ip>/ufmRestV2/reources/systems
```

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/errors or Apache logs AH01842, it must:

Delete the session cookie from its cookie jar, or call GET /logout.
Authenticate again through POST /dologin.
Store and use the newly issued session cookie.

Clients using per-request Basic authentication are not affected.

Token-Based Authentication

For token-based authentication, follow the below instructions

Create an access token using either the user's credentials or session:

curl -k -X POST https://<ufm-ip>/ufmRest/app/tokens -u username:password

Access ufmRestV3 using the access token generated earlier:

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

LDAP-Based Authentication

To authenticate via the configured by the user LDAP server, run:

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

For more info, please refer to UFM Enterprise User Manual → Manage Users → Authentication Methods → LDAP Authentication

Last updated: August 27, 2026

Exposing site_name Field in REST API