Discussed in #4848

Proposal: Device Resolution by Attribute

Problem

Today, the device details page in ShellHub is only accessible using the device’s internal UID:

https://cloud.shellhub.io/devices/d1ae8d18090f7cb30e1bb827ec6775bd586c0394faacc98a7bc4c2990addce4d

This creates problems for 3rd party systems that need to link to ShellHub. These systems usually know the device by its hostname, not UID. This forces developers to write extra logic to keep data in sync, which makes integration harder.

Goal

Allow users and systems to access the device details page in ShellHub using the hostname instead of the UID, with no extra sync logic.

Proposal Overview

This proposal introduces a generic approach to resolving devices by any supported attribute, not just the hostname. The first version will support hostname, but the structure will allow easy addition of other attributes in the future

This change will need updates to both the API (@shellhub-io/backend-owners) and the UI (@shellhub-io/frontend-owners).

API Endpoint: /api/devices/resolve

Usage:

GET /api/devices/resolve?hostname=my-device-name

Parameters:

Response:

{
  "uid": "d1ae8d18090f7cb30e1bb827ec6775bd...",
  "hostname": "my-device-name",
  ....
}

NOTE: In the future, other identifiers like mac or serial_number can be supported with similar query parameters.

If the device is not found, the API returns a 404 error.

UI Route: /devices/:identifier?resolver=hostname

Examples:

• By UID (default): /devices/d1ae8d18090f7cb30e1bb827ec6775bd...
• By Hostname: /devices/my-device-name?resolver=hostname

Behavior:

If resolver=hostname is in the URL:

• The UI calls /api/devices/resolve?hostname=:identifier
• Then it redirects or loads /devices/:uid internally to keep the UI behavior the same

If there is no resolver, the UI assumes :identifier is a UID and loads the page directly according to the current behavior.

Benefits

• Makes the UI route simple and consistent (/devices/:identifier), regardless of the identifier type
• The resolver parameter keeps it clear and explicit what kind of identifier is being used
• External systems can generate device links using only the hostname, without needing to fetch the UID first
• Reduces integration complexity and removes the need for custom sync logic
• The API becomes more flexible by allowing queries using different types of identifiers (hostname, mac, etc.)
• Easy to extend the solution in the future, with minimal changes to the API and UI