Links REST API | UFM REST API Guide

Description – Provides information on all links within the fabric, links connected to a specific system, or detailed link information including cable data.
Request URL – GET /ufmRest/resources/links
Main OperationsGet all linksGet all links connected to a specific systemGet all link/s with their cable information

Important: For InfiniBand network devices that support port labels (e.g., XDR, NDR switches, HCAs of type ConnectX--6 or later), the source and destination port dname will include port labels (e.g., "destination_port_dname": "1/3/1"). For other types, only the port number will be displayed.

Get All Links

Description – Retrieves information on all links in the fabric.
Request URL – ^{GET /ufmRest/resources/links}
Request Content Type – Application/json

Response Example:

[
    {
        "source_guid": "900a840300ac8c40",
        "source_port": "5",
        "destination_guid": "9c0591030085abc0",
        "destination_port": "5",
        "source_port_dname": "1/3/1",
        "source_port_name": "900a840300ac8c40_5",
        "destination_port_dname": "1/3/1",
        "destination_port_name": "9c0591030085abc0_5",
        "width": "4x",
        "severity": "Info",
        "source_port_node_description": "sw-ufm-ndr03:1/3/1",
        "destination_port_node_description": "sw-ufm-ndr04:1/3/1",
        "name": "900a840300ac8c40_5:9c0591030085abc0_5",
        "capabilities": [
            "collect_system_dump"
        ]
    },
  
]
...

Status Codes
- 200 – OK

Get All Links Connected to a Specific System

Description – Retrieves information on all links connected to a system identified by the system name.
Request URL – GET /ufmRest/resources/links?system=<system-name>
Request Content Type – Application/json

Response

[
    {
        "source_guid": "900a840300ac8c40",
        "source_port": "10",
        "destination_guid": "9c0591030085abc0",
        "destination_port": "10",
        "source_port_dname": "1/5/2",
        "source_port_name": "900a840300ac8c40_10",
        "destination_port_dname": "1/5/2",
        "destination_port_name": "9c0591030085abc0_10",
        "width": "4x",
        "severity": "Info",
        "source_port_node_description": "sw-ufm-ndr03:1/5/2",
        "destination_port_node_description": "sw-ufm-ndr04:1/5/2",
        "name": "900a840300ac8c40_10:9c0591030085abc0_10",
        "capabilities": [
            "collect_system_dump"
        ]
    },
    {
        "source_guid": "900a840300ac8c40",
        "source_port": "6",
        "destination_guid": "9c0591030085abc0",
        "destination_port": "6",
        "source_port_dname": "1/3/2",
        "source_port_name": "900a840300ac8c40_6",
        "destination_port_dname": "1/3/2",
        "destination_port_name": "9c0591030085abc0_6",
        "width": "4x",
        "severity": "Info",
        "source_port_node_description": "sw-ufm-ndr03:1/3/2",
        "destination_port_node_description": "sw-ufm-ndr04:1/3/2",
        "name": "900a840300ac8c40_6:9c0591030085abc0_6",
        "capabilities": [
            "collect_system_dump"
        ]
    },
     {
        "source_guid": "900a840300ac8c40",
        "source_port": "2",
        "destination_guid": "b8599f0300fc6de4",
        "destination_port": "8",
        "source_port_dname": "1/1/2",
        "source_port_name": "900a840300ac8c40_2",
        "destination_port_dname": "8",
        "destination_port_name": "b8599f0300fc6de4_8",
        "width": "4x",
        "severity": "Info",
        "source_port_node_description": "sw-ufm-ndr03:1/1/2",
        "destination_port_node_description": "r-ufm-sw95:8",
        "name": "900a840300ac8c40_2:b8599f0300fc6de4_8",
        "capabilities": [
            "collect_system_dump"
        ]
    },
    {
        "source_guid": "900a840300ac8c40",
        "source_port": "65",
        "destination_guid": "900a840300ac8c48",
        "destination_port": "1",
        "source_port_dname": "65",
        "source_port_name": "900a840300ac8c40_65",
        "destination_port_dname": "1",
        "destination_port_name": "900a840300ac8c48_1",
        "width": "4x",
        "severity": "Info",
        "source_port_node_description": "sw-ufm-ndr03:65",
        "destination_port_node_description": "Mellanox Technologies Aggregation Node",
        "name": "900a840300ac8c40_65:900a840300ac8c48_1",
        "capabilities": []
    }
]

Status Codes
- 200 – OK

Get Link/s With Cable Information

Description – Retrieves detailed information on one or more links, including their cable data.
Request URL
GET /ufmRest/resources/links?cable_info=<'true'/'True'/'TRUE'/'t'/'T'>
or
GET /ufmRest/resources/links?system=<system-name>&cable_info=<'true'/'True'/'TRUE'/'t'/'T'>
Request Content Type – Application/json

Possible Filters – optional request parameter that can be used as a filter:

Parameter	Value	Description
`monitoring_counters_info`	true	Returns monitoring counters for source and destination ports.

Response

[
    {
        "source_guid": "900a840300ac8c40",
        "source_port": "10",
        "destination_guid": "9c0591030085abc0",
        "destination_port": "10",
        "source_port_dname": "1/5/2",
        "source_port_name": "900a840300ac8c40_10",
        "destination_port_dname": "1/5/2",
        "destination_port_name": "9c0591030085abc0_10",
        "width": "4x",
        "severity": "Info",
        "source_port_node_description": "sw-ufm-ndr03:1/5/2",
        "destination_port_node_description": "sw-ufm-ndr04:1/5/2",
        "name": "900a840300ac8c40_10:9c0591030085abc0_10",
        "capabilities": [
            "collect_system_dump"
        ],
        "cable_info": {
            "technology": "1310 nm EML",
            "fw_version": "79.147.0",
            "serial_number": "MT2323NS04596",
            "part_number": "MMS4X00-NS",
            "length": "147.6 m",
            "revision": "B1",
            "temperature": "64C",
            "identifier": "OSFP"
        }
    },

    {
        "source_guid": "900a840300ac8c40",
        "source_port": "4",
        "destination_guid": "9c0591030085abc0",
        "destination_port": "3",
        "source_port_dname": "1/2/2",
        "source_port_name": "900a840300ac8c40_4",
        "destination_port_dname": "1/2/1",
        "destination_port_name": "9c0591030085abc0_3",
        "width": "4x",
        "severity": "Info",
        "source_port_node_description": "sw-ufm-ndr03:1/2/2",
        "destination_port_node_description": "sw-ufm-ndr04:1/2/1",
        "name": "900a840300ac8c40_4:9c0591030085abc0_3",
        "capabilities": [
            "collect_system_dump"
        ],
        "cable_info": {
            "technology": "1310 nm EML",
            "fw_version": "79.252.0",
            "serial_number": "MT2324NS02438",
            "part_number": "MMS4X00-NS",
            "length": "6.6 m",
            "revision": "B1",
            "temperature": "54C",
            "identifier": "OSFP"
        }
    },
    {
        "source_guid": "900a840300ac8c40",
        "source_port": "9",
        "destination_guid": "9c0591030085abc0",
        "destination_port": "9",
        "source_port_dname": "1/5/1",
        "source_port_name": "900a840300ac8c40_9",
        "destination_port_dname": "1/5/1",
        "destination_port_name": "9c0591030085abc0_9",
        "width": "4x",
        "severity": "Info",
        "source_port_node_description": "sw-ufm-ndr03:1/5/1",
        "destination_port_node_description": "sw-ufm-ndr04:1/5/1",
        "name": "900a840300ac8c40_9:9c0591030085abc0_9",
        "capabilities": [
            "collect_system_dump"
        ],
        "cable_info": {
            "technology": "1310 nm EML",
            "fw_version": "46.150.28",
            "serial_number": "MT2425FT14194",
            "part_number": "MMS4X00-NM",
            "length": "147.6 m",
            "revision": "A3",
            "temperature": "61C",
            "identifier": "OSFP"
        }
    }
]

Status Codes
- 200 – OK

Get Cable Information

Description – Retrieves information on a specific cable or multiple cables.
Request URL –
GET /ufmRest/resources/links?cable_serial=<S/N of the cable>
Or
GET /ufmRest/resources/links?cable_serial=<S/N of cable#1, S/N of cable#2, S/N of cable#3>
Request Content Type – Application/json

Response

[
  {
    "source_guid": "248a0703002e6222",
    "source_port": "1",
    "destination_guid": "e41d2d0300062380",
    "destination_port": "3",
    "source_port_dname": "HCA-1\/1",
    "destination_port_dname": "3",
    "width": "IB_4x",
    "severity": "Info",
    "name": "248a0703002e6222_1:e41d2d0300062380_3"
  }
]

Status Codes
- 200 – OK

Get Switch Port Cable Information

Description – Retrieves cable information for switch ports.
Request URL – POST /ufmRest/actions
Request Content Type – application/json

Request Data

{
  "params": {
    "port_id": "0002c9030060dc20_11"
  },
  "action": "get_cables_info",
  "object_ids": [
    "0002c9030060dc20"
  ],
  "object_type": "System",
  "description": "",
  "identifier": "id"
}

Response

{
  "troubleshooting_info": {
    "Recommendation": "No issue was observed.",
    "Status Opcode": "0",
    "Group Opcode": "N/A"
  },
  "module_info": {
    "Attenuation (5g,7g,12g) [dB]": "4,5,9",
    "Rev": "A2",
    "CDR RX": "",
    "Voltage [mV]": "N/A",
    "Vendor Part Number": "MCP1600-E001",
    "Rx Power Current [dBm]": "N/A",
    "OUI": "Mellanox",
    "Digital Diagnostic Monitoring": "No",
    "Transfer Distance [m]": "1",
    "LOS Alarm": "N/A",
    "Temperature [C]": "N/A",
    "Cable Technology": "Copper cable unequalized",
    "Tx Power Current [dBm]": "N/A",
    "Bias Current [mA]": "N/A",
    "Power Class": "1.5 W max",
    "Compliance": "N/A",
    "Vendor Serial Number": "MT1623VS01862",
    "Wavelength [nm]": "N/A",
    "Identifier": "QSFP+",
    "FW Version": "N/A",
    "CDR TX": "",
    "Cable Type": "Passive copper cable",
    "Vendor Name": "Mellanox"
  },
  "operational_info": {
    "FEC": "No FEC",
    "Auto Negotiation": "ON",
    "Loopback Mode": "No Loopback",
    "Physical state": "LinkUp",
    "Width": "0x",
    "State": "Active",
    "Speed": "IB-EDR"
  },
  "supported_info": {
    "Enabled Link Speed": "0x0000003f (EDR,FDR,FDR10,QDR,DDR,SDR)",
    "Supported Cable Speed": "0x0000003f (EDR,FDR,FDR10,QDR,DDR,SDR)"
  }
}

Status Codes
- 202 – ACCEPTED
- 400 – BAD_REQUEST
- 404 – NOT_FOUND
- 403 – FORBIDDEN

Last updated: January 28, 2025