Exclude software when using the `GET /hosts/identifier/:identifier` API endpoint

Patagonia121 commented 1 month ago

Goal

User story
As a user integrating w/ Fleet's GET /hosts/identifier/:identifier API endpoint,
I want to exclude the `software` array from the response
so that I when I'm looking at the raw response I don't have to scroll through a bunch of results to find the hosts `seen_time`.

Context

Product designer: @rachaelshaw

Changes

Product

[ ] UI changes: No UI changes.
[ ] CLI usage changes: No CLI changes.
[ ] REST API changes: PR is here.
[ ] Reference documentation changes: Update the "Get host by identifier" endpoint in the REST API docs to include the new parameter: https://fleetdm.com/docs/rest-api/rest-api#get-host-by-identifier
[ ] Fleet's agent (fleetd) changes: No fleetd changes
[ ] Permissions changes: No permissions changes.
[ ] Changes to paid features or tiers: Available in Fleet Free and Fleet Premium

Engineering

[ ] Usage documentation changes: TODO
[ ] Database schema migrations: TODO
[ ] Load testing: TODO

ℹ️ Please read this issue carefully and understand it. Pay special attention to UI wireframes, especially "dev notes".

QA

Risk assessment

Risk level: Low

Manual testing steps

Test api/v1/fleet/hosts/identifier/:identifier endpoint.

without any options
with exclude_software=true
with exclude_software=false
with exclude_software=bozo // defaults to false

Testing notes

Confirmation

[x] Engineer (@getvictor): Added comment to user story confirming successful completion of QA.
[ ] QA (@____): Added comment to user story confirming successful completion of QA.

JoStableford commented 1 month ago

Related to a Slack conversation

noahtalerman commented 1 month ago

Hey @Patagonia121! Thanks for tracking this.

The software inventory in Fleet can create a poor user experience if there's a customer that has to scroll through a bunch of raw results

When you get the chance, can you please help dig into this? What workflow exactly is the customer trying to do?

Example workflow (Noah's guess): As the customer, I'm calling the GET /hosts/identifier:identifier API endpoint in Postman and looking at the response to try to find this host's last seen_time. This is painful because I have to scroll past the software array to see seen_time.

Note that this workflow includes not only the workflow but the tool the customer is using.

Maybe we can ask the customer to follow up in this issue?

getvictor commented 1 month ago

Related issues:

Fix for #19348 added exclude_software to /api/latest/hosts/:id endpoint.
19618 should add exclude_software to device/:identifier endpoint.

Patagonia121 commented 1 month ago

@noahtalerman - I reached out to the customer and will update once they respond (also shared your comment with them).

mostlikelee commented 1 week ago

@jamesfkane has an open PR on this. @jamesfkane can you provide a bit of info on what makes this feature useful to you?

CC: @noahtalerman

lukeheath commented 1 week ago

@noahtalerman Sending this to product board for review because we received a community PR that addresses it.

jamesfkane commented 1 week ago

Sounds like you already have what you need, but to add, when building automations using the GET /api/v1/fleet/hosts/identifier/:identifier endpoint and potentially looping through thousands of devices where the use case doesn't require software details, the option to exclude it significantly reduces the data in each response.

noahtalerman commented 1 week ago

Thanks @jamesfkane!

When you get the chance, can you please update the REST API docs in your PR?

It looks like we want to update the "Parameters" table for the "Get host by identifier" endpoint in the REST API docs to include the new parameter: https://fleetdm.com/docs/rest-api/rest-api#parameters28

noahtalerman commented 1 week ago

@lukeheath heads up, I updated this issue to user story and assigned it to @rachaelshaw (API design DRI)

Rachael, when you get the chance can you please take a look at the proposed API changes? If they look good to go, can you please move this story to the release board and assign @sharon-fdm so that it can be QA'd? Thanks!

rachaelshaw commented 1 week ago

✅ Approved the API change — it's consistent with what we currently have for Get host

noahtalerman commented 1 week ago

@sharon-fdm heads up, I pulled this off of the drafting board (:product). Rachael moved it to the release board.

cc @lukeheath

sharon-fdm commented 1 week ago

@noahtalerman is it a P2 for next sprint? If so, should we not keep it high on the product board (with P2)?

sharon-fdm commented 1 week ago

Hey team! Please add your planning poker estimate with Zenhub @getvictor @jacobshandling @lucasmrod @mostlikelee @RachelElysia

noahtalerman commented 1 week ago

is it a P2 for next sprint? If so, should we not keep it high on the product board (with P2)?

Hey @sharon-fdm! Not a P2.

My understanding, based on @lukeheath's proposed process for community PRs here in Slack (internal) is that we'd pull it into the current sprint.

sharon-fdm commented 6 days ago

@noahtalerman, NP. We can assign next sprint.

fleetdm / fleet