Device Reference Helper

Overview

Many BIG-IQ API requests refer to a particular BIG-IP using the deviceReference parameter. The value of deviceReference is a link object for the BIG-IP being targeted by the request. You should first call the Device Reference Helper API to get the correct value of deviceReference before trying to use it in another BIG-IQ API. The value of these links is expected to change from release to release. The helper API can query for the correct value of deviceReference if you specify either the hostname, address, or machineId of the target BIG-IP as well as specify the module associated with your request. By using the helper API, you will isolate clients from future version-specific changes to these links.

The MachineId Resolver API can retrieve a device object, with some informational properties, for all of the currently trusted BIG-IPs on the system.

REST Endpoint: /mgmt/cm/shared/device-reference-query

Requests

POST /mgmt/cm/shared/device-reference-query

Request Parameters

Name Type Required Description
machineId string If machineId is not null, use it to identify the BIG-IP, otherwise use address. The machineId of the target BIG-IP.
address string If address is not null, use it to identify the BIG-IP, otherwise use hostname. The IP address of the target BIG-IP.
hostname string At least one of machineId, address, or hostname is required to identify the BIG-IP. The hostname of the target BIG-IP.
module string If module is null or empty, BIG-IQ uses a default value of “global”. Name representing the module and the device group reference associated with the API request. See the following table for the allowed values of module.

The following names can be used as the value of module.

Name Device Group Reference
access cm-access-allBigIpDevices
adc-core cm-adccore-allbigipDevices
asm cm-asm-allAsmDevice
global cm-bigip-allBigIpDevices
dns cm-dns-allBigIpDevices
firewall cm-firewall-allFirewallDevices
security-shared cm-security-shared-allSharedDevices
websafe cm-websafe-allFpsDevices

Query Parameters

None

Response

HTTP/1.1 200 OK

Name Type Description
link object The value of the deviceReference parameter.

Error Response

HTTP/1.1 404 Not Found

This response happens if that BIG-IP cannot be found or does not exist in that module.

Permissions

Role Allow
All Roles Yes

Examples

POST to retrieve deviceReference for PUT

In the following example, the BIG-IQ API is going to use the deviceReference parameter to target a particular BIG-IP for a PUT request. First, call the Device Reference Helper to get the correct value of deviceReference as follows.

POST https://<BIG-IQ>/mgmt/cm/shared/device-reference-query

The JSON in the body of the POST can look similar to the following.

{
        "address": "192.0.0.106",
        "module": "access"
}

On success, the body of the response contains the link object which is the value of deviceReference.

{
        "link": "https://localhost/mgmt/shared/resolver/device-groups/cm-access-allBigIpDevices/devices/2913a9ff-6fea-42a1-bd82-73d6dd5c9849"
}

You can then use this value in the PUT request as the follows.

PUT https://<BIG-IQ>/mgmt/cm/access/working-config/ltm/virtual/<id>

The JSON in the body of the PUT can look similar to the following.

{
        "name": "vip-02",
        "deviceReference": {
                "link": "https://localhost/mgmt/shared/resolver/device-groups/cm-access-allBigIpDevices/devices/2913a9ff-6fea-42a1-bd82-73d6dd5c9849"
        }
}

POST to get deviceReference using machineId

The following example uses the BIG-IP’s machineId to retrieve the value of deviceReference for all device groups of the BIG-IP.

POST https://<BIG-IQ>/mgmt/cm/shared/device-reference-query

The JSON in the body of the POST request can look similar to the following. If module is null or empty, BIG-IQ uses a default value of “global”.

{
        "machineId": "20d984d2-9da5-4b59-b78b-54d7bd6d11f2"
}

The JSON in the body of the response can look similar to the following.

{
        "link": "https://localhost/mgmt/shared/resolver/device-groups/cm-bigip-allBigIpDevices/devices/7703cfab-ead2-4abd-984d-b61f259f705d"
}

You can then send a GET request to this link to retrieve the device object for the BIG-IP.

GET https://<BIG-IQ>/mgmt/shared/resolver/device-groups/cm-bigip-allBigIpDevices/devices/7703cfab-ead2-4abd-984d-b61f259f705d

The JSON in the body of the response can look similar to the following.

{
        "kind": "shared:resolver:device-groups:restdeviceresolverdevicestate",
        "uuid": "7703cfab-ead2-4abd-984d-b61f259f705d",
        "build": "0.0.6",
        "slots": [{
                "build": "0.0.6",
                "volume": "HD1.1",
                "product": "BIG-IP",
                "version": "13.1.3",
                "isActive": true
        }],
        "state": "ACTIVE",
        "address": "10.144.75.194",
        "edition": "Final",
        "product": "BIG-IP",
        "version": "13.1.3",
        "hostname": "joey.bipip13One3.com",
        "selfLink": "https://localhost/mgmt/shared/resolver/device-groups/cm-bigip-allBigIpDevices/devices/7703cfab-ead2-4abd-984d-b61f259f705d",
        "deviceUri": "https://10.144.75.194:443",
        "groupName": "cm-bigip-allBigIpDevices",
        "httpsPort": 443,
        "isVirtual": true,
        "machineId": "7703cfab-ead2-4abd-984d-b61f259f705d",
        "generation": 4,
        "properties": {
                "shared:resolver:device-groups:discoverer": "20d984d2-9da5-4b59-b78b-54d7bd6d11f2"
        },
        "isClustered": false,
        "mcpDeviceName": "/Common/joey.bipip13One3.com",
        "trustDomainGuid": "8071dd39-c223-4b3c-bc63fa163e83a778",
        "isLicenseExpired": false,
        "lastUpdateMicros": 1575324951435097,
        "managementAddress": "10.144.75.194",
        "restFrameworkVersion": "13.1.3-0.0.6"
}

POST to get deviceReference using machineId

The following example uses the BIG-IP’s machineId to retrieve the value of deviceReference and specifies the device group associated with cm-adccore-allbigipDevices.

POST https://<BIG-IQ>/mgmt/cm/shared/device-reference-query

The JSON in the body of the POST request can look similar to the following.

{
        "machineId": "20d984d2-9da5-4b59-b78b-54d7bd6d11f2",
        "module": "adc-core"
}

The JSON in the body of the response can look similar to the following.

{
        "link": "https://localhost/mgmt/shared/resolver/device-groups/cm-adccore-allbigipDevices/devices/7703cfab-ead2-4abd-984d-b61f259f705d"
}