Skip to content

ADR devices export api

Jump to bottom
ShradhaGupta31 edited this page Jul 7, 2026 · 2 revisions

Design: /api/v1/devices/export — Device Data Export API

GitHub Issue: device-management-toolkit/console#1076
Parent: Console Discovery Dashboard & Device Data Export #1093
Status: In Grooming

Overview

Introduce a new Console API endpoint that exports all device data (including deviceInfo) in JSON (and optionally CSV) format. This enables fleet operators to extract a complete snapshot of managed and discovered devices for reporting, auditing, and tooling integration.

Endpoint: GET /api/v1/devices/export

Proposed JSON Schema

The export wraps all device records. Each record exposes the full Device and DeviceInfo fields as defined in the current DTO.

Discussion point: The current DB/API stores deviceInfo as a flat blob. The proposed export response groups fields into amt, os, and bmc sections for readability. See Open Questions for the trade-offs.

Option A — Current flat structure (as stored in DB today)

{
  "guid": "143e4567-e89b-12d3-a456-426614174000",
  "hostname": "lab-pc-01",
  "friendlyName": "Lab PC Alpha",
  "tags": ["campus-lab", "shared-device"],
  "tenantId": "",
  "dnsSuffix": "corp.example.com",
  "connectionStatus": true,
  "lastConnected": "2026-07-07T05:30:00Z",
  "lastSeen": "2026-07-07T06:00:00Z",
  "lastDisconnected": null,
  "deviceInfo": {
    "amtEnabledInBIOS": true,
    "currentMode": "Admin",
    "discovered": true,
    "fwVersion": "16.1.32",
    "fwBuild": "3400",
    "fwSku": "16392",
    "features": "AMT Pro Corporate",
    "lmsInstalled": true,
    "lmsVersion": "2410.5.0.0",
    "meInterfaceVersion": "16.1.25.2124",
    "tlsMode": "TLS 1.2",
    "ipAddress": "10.0.0.12",
    "osName": "linux",
    "osVersion": "6.8.0-51-generic",
    "osDistro": "Ubuntu 24.04 LTS",
    "osIpAddress": "10.49.76.163",
    "cpuModel": "Intel(R) Core(TM) Ultra 7 165H",
    "dhcpEnabled": true,
    "ethernetAdapterCount": 2,
    "monitorConnected": true,
    "ieee8021xEnabled": false,
    "certHashes": ["a1b2c3", "d4e5f6"],
    "upid": {
      "csmeId": "4A45A39C5ED9462082510000",
      "oemId": "",
      "oemPlatformIdType": "Not Set (0)"
    },
    "lastUpdated": "2026-05-21T00:00:00Z"
  }
}

Decision for Option 1: All AMT, OS, and peripheral fields are mixed into a single flat blob. As more peripherals are added (e.g. BMC, future hardware interfaces), the flat list grows unmanageably. Consumers of the export have no easy way to understand which fields belong to which subsystem without reading documentation.

Option B — Proposed nested structure (grouped for export readability)

{
  "guid": "143e4567-e89b-12d3-a456-426614174000",
  "hostname": "lab-pc-01",
  "friendlyName": "Lab PC Alpha",
  "tags": ["campus-lab", "shared-device"],
  "dnsSuffix": "corp.example.com",
  "deviceInfo": {
    "currentMode": "Admin",
    "amt": {
      "amtEnabledInBIOS": true,
      "fwVersion": "16.1.32",
      "fwBuild": "3400",
      "fwSku": "16392",
      "features": "AMT Pro Corporate",
      "tlsMode": "TLS 1.2",
      "lmsInstalled": true,
      "lmsVersion": "2410.5.0.0",
      "meInterfaceVersion": "16.1.25.2124",
      "dhcpEnabled": true,
      "certHashes": ["a1b2c3", "d4e5f6"],
      "upid": {
        "csmeId": "4A45A39C5ED9462082510000",
        "oemId": "",
        "oemPlatformIdType": "Not Set (0)"
      },
      "network": {
        "wired": {
          "ipAddress": "10.0.0.12",
          "dhcp": true,
          "static": false
        },
        "wireless": {
          "ipAddress": "192.168.1.20"
        }
      }
    },
    "os": {
      "name": "linux",
      "version": "6.8.0-51-generic",
      "distro": "Ubuntu 24.04 LTS",
      "cpu": "Intel(R) Core(TM) Ultra 7 165H",
      "monitorConnected": true,
      "ethernetAdapterCount": 2,
      "ieee8021xEnabled": false,
      "network": {
        "wired": [
          {
            "name": "eth0",
            "ipAddress": "10.49.76.163",
            "macAddress": "AA:BB:CC:DD:EE:FF"
          },
          {
            "name": "eth1",
            "ipAddress": "10.49.76.164",
            "macAddress": "AA:BB:CC:DD:EE:00"
          }
        ],
        "wireless": {
          "ipAddress": "10.0.2.25"
        }
      }
    },
    "bmc": {
      "vendor": "string",
      "model": "string",
      "firmwareVersion": "string"
    }
  }
}

Fields are grouped by subsystem (amt, os, bmc). Adding new peripheral data tomorrow (e.g. BMC firmware version, future HW interfaces) means adding a new top-level section under deviceInfo — no consumer needs to guess which fields belong where. Network details are scoped to the subsystem that reported them (amt.network vs os.network).

API Design

Request

GET /api/v1/devices/export
Authorization: Bearer <token>
Accept: application/json        (default)
Accept: text/csv                (for CSV export)

Response (JSON)

{
  "totalCount": 4,
  "exportedAt": "2026-07-07T06:00:00Z",
  "data": [
    {
      "guid": "143e4567-e89b-12d3-a456-426614174000",
      "hostname": "lab-pc-01",
      "friendlyName": "Lab PC Alpha",
      "tags": ["campus-lab", "shared-device"],
      "dnsSuffix": "corp.example.com",
      "deviceInfo": {
        "currentMode": "Admin",
        "discovered": true,
        "lastUpdated": "2026-07-07T05:00:00Z",
        "amt": {
          "amtEnabledInBIOS": true,
          "fwVersion": "16.1.32",
          "fwBuild": "3400",
          "fwSku": "16392",
          "features": "AMT Pro Corporate",
          "tlsMode": "TLS 1.2",
          "lmsInstalled": true,
          "lmsVersion": "2410.5.0.0",
          "meInterfaceVersion": "16.1.25.2124",
          "dhcpEnabled": true,
          "certHashes": ["a1b2c3", "d4e5f6"],
          "upid": {
            "csmeId": "4A45A39C5ED9462082510000",
            "oemId": "",
            "oemPlatformIdType": "Not Set (0)"
          },
          "network": {
            "wired": { "ipAddress": "10.0.0.12", "dhcp": true, "static": false },
            "wireless": { "ipAddress": "192.168.1.20" }
          }
        },
        "os": {
          "name": "linux",
          "version": "6.8.0-51-generic",
          "distro": "Ubuntu 24.04 LTS",
          "cpu": "Intel(R) Core(TM) Ultra 7 165H",
          "monitorConnected": true,
          "ethernetAdapterCount": 2,
          "ieee8021xEnabled": false,
          "network": {
            "wired": [
              { "name": "eth0", "ipAddress": "10.49.76.163", "macAddress": "AA:BB:CC:DD:EE:FF" },
              { "name": "eth1", "ipAddress": "10.49.76.164", "macAddress": "AA:BB:CC:DD:EE:00" }
            ],
            "wireless": { "ipAddress": "10.0.2.25" }
          }
        },
        "bmc": {
          "vendor": "AMI",
          "model": "MegaRAC",
          "firmwareVersion": "1.2.3"
        }
      }
    },
    {
      "guid": "243e4567-e89b-12d3-a456-426614174001",
      "hostname": "lab-pc-02",
      "friendlyName": "Lab PC Beta",
      "tags": ["campus-lab"],
      "dnsSuffix": "corp.example.com",
      "deviceInfo": {
        "currentMode": "client control mode",
        "discovered": true,
        "lastUpdated": "2026-07-06T18:00:00Z",
        "amt": {
          "amtEnabledInBIOS": true,
          "fwVersion": "16.0.15",
          "fwBuild": "3100",
          "fwSku": "8",
          "features": "AMT Pro",
          "tlsMode": "TLS 1.2",
          "lmsInstalled": true,
          "lmsVersion": "2410.5.0.0",
          "meInterfaceVersion": "16.0.15.1900",
          "dhcpEnabled": true,
          "certHashes": ["c3d4e5"],
          "upid": {
            "csmeId": "5B56B40D6FEA573193620111",
            "oemId": "",
            "oemPlatformIdType": "Not Set (0)"
          },
          "network": {
            "wired": { "ipAddress": "10.0.0.13", "dhcp": true, "static": false },
            "wireless": null
          }
        },
        "os": {
          "name": "windows",
          "version": "10.0.19045",
          "distro": "Windows 10 Enterprise",
          "cpu": "Intel(R) Core(TM) i5-1235U",
          "monitorConnected": false,
          "ethernetAdapterCount": 1,
          "ieee8021xEnabled": false,
          "network": {
            "wired": [
              { "name": "Ethernet", "ipAddress": "10.49.76.170", "macAddress": "BB:CC:DD:EE:FF:00" }
            ],
            "wireless": null
          }
        },
        "bmc": null
      }
    },
    {
      "guid": "343e4567-e89b-12d3-a456-426614174002",
      "hostname": "discovered-pc-01",
      "friendlyName": "",
      "tags": [],
      "dnsSuffix": "",
      "deviceInfo": {
        "currentMode": "not activated",
        "discovered": true,
        "lastUpdated": "2026-07-07T03:15:00Z",
        "amt": {
          "amtEnabledInBIOS": true,
          "fwVersion": "15.0.45",
          "fwBuild": "2900",
          "fwSku": "16400",
          "features": "Intel Standard Manageability Corporate",
          "tlsMode": null,
          "lmsInstalled": false,
          "lmsVersion": null,
          "meInterfaceVersion": "15.0.45.2100",
          "dhcpEnabled": true,
          "certHashes": [],
          "upid": null,
          "network": {
            "wired": { "ipAddress": "10.0.0.20", "dhcp": true, "static": false },
            "wireless": null
          }
        },
        "os": {
          "name": "linux",
          "version": "5.15.0-91-generic",
          "distro": "Ubuntu 22.04 LTS",
          "cpu": "Intel(R) Core(TM) i3-1115G4",
          "monitorConnected": false,
          "ethernetAdapterCount": 1,
          "ieee8021xEnabled": false,
          "network": {
            "wired": [
              { "name": "eth0", "ipAddress": "10.49.76.180", "macAddress": "CC:DD:EE:FF:00:11" }
            ],
            "wireless": null
          }
        },
        "bmc": null
      }
    },
    {
      "guid": "443e4567-e89b-12d3-a456-426614174003",
      "hostname": "lab-server-01",
      "friendlyName": "Lab Server Rack A",
      "tags": ["server", "rack-a"],
      "dnsSuffix": "corp.example.com",
      "deviceInfo": {
        "currentMode": "Admin",
        "discovered": false,
        "lastUpdated": "2026-07-05T12:00:00Z",
        "amt": {
          "amtEnabledInBIOS": true,
          "fwVersion": "16.1.32",
          "fwBuild": "3400",
          "fwSku": "16392",
          "features": "AMT Pro Corporate",
          "tlsMode": "TLS 1.3",
          "lmsInstalled": true,
          "lmsVersion": "2410.5.0.0",
          "meInterfaceVersion": "16.1.32.2200",
          "dhcpEnabled": false,
          "certHashes": ["f1e2d3", "a4b5c6"],
          "upid": {
            "csmeId": "6C67C51E7GFB684204730222",
            "oemId": "DELL",
            "oemPlatformIdType": "Type 1"
          },
          "network": {
            "wired": { "ipAddress": "10.0.1.5", "dhcp": false, "static": true },
            "wireless": null
          }
        },
        "os": {
          "name": "linux",
          "version": "6.5.0-45-generic",
          "distro": "Ubuntu 22.04 LTS",
          "cpu": "Intel(R) Xeon(R) E-2386G",
          "monitorConnected": false,
          "ethernetAdapterCount": 4,
          "ieee8021xEnabled": true,
          "network": {
            "wired": [
              { "name": "eth0", "ipAddress": "10.49.77.5", "macAddress": "DD:EE:FF:00:11:22" },
              { "name": "eth1", "ipAddress": "10.49.77.6", "macAddress": "DD:EE:FF:00:11:23" },
              { "name": "eth2", "ipAddress": "10.49.77.7", "macAddress": "DD:EE:FF:00:11:24" },
              { "name": "eth3", "ipAddress": "10.49.77.8", "macAddress": "DD:EE:FF:00:11:25" }
            ],
            "wireless": null
          }
        },
        "bmc": {
          "vendor": "Dell",
          "model": "iDRAC9",
          "firmwareVersion": "6.10.30.10"
        }
      }
    }
  ]
}

Open Questions

1. Where will wired/wireless network fields come from?

The proposed JSON example includes amt.network.wired, amt.network.wireless, os.network.wired[], and os.network.wireless. These fields do not currently exist in DeviceInfo.

  • Does this require extending rpc amtinfo --sync to collect network adapter details?
  • Does this require a DB schema update (new fields in the deviceInfo JSON blob)?

2. DB schema alignment

The proposed export JSON uses a nested structure (amt.{}, os.{}, bmc.{}), but the DB today stores deviceInfo as a flat JSON blob.

  • Do we need to update the DB schema to match the nested structure, or do we keep the flat blob and transform it at the API layer on export?
  • If we keep the flat DB schema and only reshape on export: any future change to the DB field names or structure will silently break the export API. Who is responsible for keeping the mapping in sync?
  • If we update the DB to store the nested structure: this is a breaking migration — all existing deviceInfo rows need to be migrated, and every writer (rpc amtinfo --sync, Console API) needs to be updated.

3. Do we need export metadata?

Should the response include Dicovery feilds as well fields such as:

  • exportedAt
  • exportedBy
  • lastUpdated
  • lastDiscovered

4. Do we need a summary section?

Should the export include aggregated counts such as:

  • Total devices
  • Activated vs. not activated count
  • Discovered count
  • vPro count vs. ISM count

Console Wiki

ADRs

Clone this wiki locally