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:
-
In the
[Server]section ofgv.cfg, set a value forsite_name. -
In the
[Server]section ofgv.cfg, setexpose_site_nametotrue. -
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:
-
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 -
Use the saved session to make as many
ufmRestV2requests as needed. For example: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 or errors, or Apache logs AH01842, it must:
-
Delete the
sessioncookie from its cookie jar, or callGET /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
To use token-based authentication, follow these steps:
-
Create an access token using either your credentials or your session:
curl -k -X POST https://<ufm-ip>/ufmRest/app/tokens -u username:password -
Send requests to
ufmRestV3with 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: