host identifiers in the docs, CLI and API are confusing and not well defined

[roperzh]

Problem

As an IT admin or security admin trying to interact with the Fleet CLI and API, the documentation in fleetctl and the API docs is not clear when it comes to "host identifiers"

Host identifier is described in the errors and docs as: a valid hostname, UUID, osquery host ID, or node key.

Some of the problems:

• When you go to the UI, we have two columns:Host and Hostname, people generally grab the value from Host and get an error.
• Many people would expect to be able to provide a host id as well in this endpoint
• Some values have confusing names and are not explained as part of the error, eg: what's a "node key"?

Potential solutions

• Improve our error messages, potentially including a link to the docs where each possible field is described
• Improve the API docs
• Not sure how to prevent people from tripping in the Host vs Hostname debacle

[noahtalerman]

Thanks for tracking this @roperzh!

I think improving the error message would be a great, quick win.

What do you think the error message should be?

[noahtalerman]

Host identifier is described in the errors and docs as: a valid hostname, UUID, osquery host ID, or node key.

Seems like a quick win here would be improving the error message and the Get host by identifier docs: https://fleetdm.com/docs/rest-api/rest-api#get-host-by-identifier