Update labels API documentation and example requests #23589
Conversation
gillespi314
commented
Nov 6, 2024
gillespi314
commented
- Adds note regarding to clarify existing API behavior when updating the list of hosts associated with a manual label based on this recent Slack thread
- Updates request/response examples to illustrate builtin and manual labels
gillespi314
temporarily deployed
to
Docker Hub
GitHub Actions
Inactive
There was a problem hiding this comment.
@rachaelshaw, I took a stab at some incremental updates to the labels API documentation based on some things that came up during my on call rotation.
I believe you took some notes/action items for yourself related to some of this in Slack so feel free to tweak this PR however makes the most sense for you :)
I tried to get the most mileage out of the two existing examples by using the create label example to illustrate dynamic labels and the modify example to illustrate manual labels. But I think it would be even better to have a set of examples for creating and modifying a dynamic label and another set of examples for creating and modifying a manual label.
| "name": "macOS hosts (x86_64)", | ||
| "description": "Filters macOS hosts with x86_64 architecture", | ||
| "query": "SELECT 1 FROM os_version WHERE platform = 'darwin' AND instr(arch, 'x86_64')", | ||
| "platform": "darwin" |
There was a problem hiding this comment.
The old example was a little confusing because there is a builtin label for Ubuntu hosts so I tried to craft an example of a dynamic label that felt more useful in practice.
| "name": "macOS label", | ||
| "description": "Now this label only includes macOS machines", | ||
| "platform": "darwin" |
There was a problem hiding this comment.
This is a bad example because the platform cannot be modified for existing labels so I revised this to be an example of how the list of hosts can be modified a manual label.
| @@ -4969,20 +4968,18 @@ Updates the specified label. Note: Label queries and platforms are immutable. To | |||
| | id | integer | path | **Required**. The label's id. | | |||
| | name | string | body | The label's name. | | |||
| | description | string | body | The label's description. | | |||
| | hosts | array | body | If updating a manual label: the list of host identifiers (`hardware_serial`, `uuid`, `osquery_host_id`, `hostname`, or `name`) the label will apply to. | | |||
There was a problem hiding this comment.
Revised to remove osquery_host_id and name based on this Slack thread.
| @@ -4969,20 +4968,18 @@ Updates the specified label. Note: Label queries and platforms are immutable. To | |||
| | id | integer | path | **Required**. The label's id. | | |||
| | name | string | body | The label's name. | | |||
| | description | string | body | The label's description. | | |||
| | hosts | array | body | If updating a manual label: the list of host identifiers (`hardware_serial`, `uuid`, `osquery_host_id`, `hostname`, or `name`) the label will apply to. | | |||
| | hosts | array | body | If updating a manual label: the list of host identifiers (`hardware_serial`, `uuid`, or `hostname`) the label will apply to. **Note: The provided list fully replaces the previous list.** | | |||
There was a problem hiding this comment.
Added this note to clarify existing behavior that the new list fully replaces the previous list based on this Slack thread.
