From b98cc6de140873f8700e9e39ea1a8f630f9fbd79 Mon Sep 17 00:00:00 2001 From: Noah Talerman Date: Wed, 11 Nov 2020 09:09:16 -0800 Subject: [PATCH 1/6] Added answer stub in updating fleet docs to answer user question. Also created rest-endpoint page in docs to document answers to users' questions about the api. --- docs/api/rest-endpoints.md | 26 ++++++++++++++++++++++++++ docs/infrastructure/updating-fleet.md | 4 ++++ 2 files changed, 30 insertions(+) create mode 100644 docs/api/rest-endpoints.md diff --git a/docs/api/rest-endpoints.md b/docs/api/rest-endpoints.md new file mode 100644 index 000000000000..290ebf83a9f6 --- /dev/null +++ b/docs/api/rest-endpoints.md @@ -0,0 +1,26 @@ +# Fleet REST API endpoints + +### Retrieve host information + +`GET /api/v1/kolide/hosts` + +DESCRIPTION TODO + +Parameters + +| Name | Type | In | Description | +|-----------------|---------|-------|-----------------| +| page | integer | query | TODO | +| per_page | integer | query | TODO | +| order_key | string | query | TODO | +| additional_info | string | query | TODO | + +EXAMPLE RESPONSE TODO + +### Retrieve metrics + +`GET /api/v1/kolide/metrics` + +DESCRIPTION TODO + +EXAMPLE RESPONSE TODO \ No newline at end of file diff --git a/docs/infrastructure/updating-fleet.md b/docs/infrastructure/updating-fleet.md index 344d2da85705..7c78b86f7657 100644 --- a/docs/infrastructure/updating-fleet.md +++ b/docs/infrastructure/updating-fleet.md @@ -60,6 +60,10 @@ fleet prepare db Note, if you would like to run this in a script, you can use the `--no-prompt` option to disable prompting before the migrations. +`Error creating db connection` + +TODO If you get the above error... + Start new Fleet server instances: ``` From 444c5dc54ef28c31ff4f51c7d6487bdeb4a7f70e Mon Sep 17 00:00:00 2001 From: Noah Talerman Date: Wed, 11 Nov 2020 13:38:02 -0800 Subject: [PATCH 2/6] Updated rest-endpoints page with more filled out information for /hosts. Removed changes to updating fleet. --- docs/api/rest-endpoints.md | 107 ++++++++++++++++++++++---- docs/infrastructure/updating-fleet.md | 4 - 2 files changed, 91 insertions(+), 20 deletions(-) diff --git a/docs/api/rest-endpoints.md b/docs/api/rest-endpoints.md index 290ebf83a9f6..72e4dced6d52 100644 --- a/docs/api/rest-endpoints.md +++ b/docs/api/rest-endpoints.md @@ -1,26 +1,101 @@ # Fleet REST API endpoints -### Retrieve host information +## Hosts -`GET /api/v1/kolide/hosts` +### List hosts -DESCRIPTION TODO +`GET /api/v1/kolide/hosts` Parameters -| Name | Type | In | Description | -|-----------------|---------|-------|-----------------| -| page | integer | query | TODO | -| per_page | integer | query | TODO | -| order_key | string | query | TODO | -| additional_info | string | query | TODO | - -EXAMPLE RESPONSE TODO - -### Retrieve metrics +| Name | Type | In | Description | +|-----------------|---------|-------|--------------------------------------------------------------------------| +| page | integer | query | Page number of the results to fetch. | +| per_page | integer | query | Results per page. | +| order_key | string | query | What to order results by. Can be any column in the hosts table.| +| additional_info | string | query | TODO | -`GET /api/v1/kolide/metrics` +Example -DESCRIPTION TODO +`GET /api/v1/kolide/hosts?page=0&per_page=100&order_key=host_name` -EXAMPLE RESPONSE TODO \ No newline at end of file +``` +{ + "hosts": [ + { + "created_at": "2020-11-05T05:09:44Z", + "updated_at": "2020-11-05T06:03:39Z", + "id": 1, + "detail_updated_at": "2020-11-05T05:09:45Z", + "label_updated_at": "2020-11-05T05:14:51Z", + "seen_time": "2020-11-05T06:03:39Z", + "hostname": "2ceca32fe484", + "uuid": "392547dc-0000-0000-a87a-d701ff75bc65", + "platform": "centos", + "osquery_version": "2.7.0", + "os_version": "CentOS Linux 7", + "build": "", + "platform_like": "rhel fedora", + "code_name": "", + "uptime": 8305000000000, + "memory": 2084032512, + "cpu_type": "6", + "cpu_subtype": "142", + "cpu_brand": "Intel(R) Core(TM) i5-8279U CPU @ 2.40GHz", + "cpu_physical_cores": 4, + "cpu_logical_cores": 4, + "hardware_vendor": "", + "hardware_model": "", + "hardware_version": "", + "hardware_serial": "", + "computer_name": "2ceca32fe484", + "primary_ip": "", + "primary_mac": "", + "distributed_interval": 10, + "config_tls_refresh": 10, + "logger_tls_period": 8, + "additional": {}, + "enroll_secret_name": "default", + "status": "offline", + "display_text": "2ceca32fe484" + }, + { + "created_at": "2020-11-05T05:09:44Z", + "updated_at": "2020-11-05T06:03:39Z", + "id": 2, + "detail_updated_at": "2020-11-05T05:09:45Z", + "label_updated_at": "2020-11-05T05:14:52Z", + "seen_time": "2020-11-05T06:03:40Z", + "hostname": "4cc885c20110", + "uuid": "392547dc-0000-0000-a87a-d701ff75bc65", + "platform": "centos", + "osquery_version": "2.7.0", + "os_version": "CentOS 6.8.0", + "build": "", + "platform_like": "rhel", + "code_name": "", + "uptime": 8305000000000, + "memory": 2084032512, + "cpu_type": "6", + "cpu_subtype": "142", + "cpu_brand": "Intel(R) Core(TM) i5-8279U CPU @ 2.40GHz", + "cpu_physical_cores": 4, + "cpu_logical_cores": 4, + "hardware_vendor": "", + "hardware_model": "", + "hardware_version": "", + "hardware_serial": "", + "computer_name": "4cc885c20110", + "primary_ip": "", + "primary_mac": "", + "distributed_interval": 10, + "config_tls_refresh": 10, + "logger_tls_period": 8, + "additional": {}, + "enroll_secret_name": "default", + "status": "offline", + "display_text": "4cc885c20110" + }, + ] +} +``` \ No newline at end of file diff --git a/docs/infrastructure/updating-fleet.md b/docs/infrastructure/updating-fleet.md index 7c78b86f7657..344d2da85705 100644 --- a/docs/infrastructure/updating-fleet.md +++ b/docs/infrastructure/updating-fleet.md @@ -60,10 +60,6 @@ fleet prepare db Note, if you would like to run this in a script, you can use the `--no-prompt` option to disable prompting before the migrations. -`Error creating db connection` - -TODO If you get the above error... - Start new Fleet server instances: ``` From 8fba36bf3defdad67fcb58f7649c78f091a341f1 Mon Sep 17 00:00:00 2001 From: Noah Talerman Date: Wed, 11 Nov 2020 13:57:50 -0800 Subject: [PATCH 3/6] Corrected paramter name to --- docs/api/rest-endpoints.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/api/rest-endpoints.md b/docs/api/rest-endpoints.md index 72e4dced6d52..72640ccc12e2 100644 --- a/docs/api/rest-endpoints.md +++ b/docs/api/rest-endpoints.md @@ -8,12 +8,12 @@ Parameters -| Name | Type | In | Description | -|-----------------|---------|-------|--------------------------------------------------------------------------| -| page | integer | query | Page number of the results to fetch. | -| per_page | integer | query | Results per page. | -| order_key | string | query | What to order results by. Can be any column in the hosts table.| -| additional_info | string | query | TODO | +| Name | Type | In | Description | +|-------------------------|---------|-------|--------------------------------------------------------------------------| +| page | integer | query | Page number of the results to fetch. | +| per_page | integer | query | Results per page. | +| order_key | string | query | What to order results by. Can be any column in the hosts table. | +| additional_info_filters | string | query | TODO | Example From 3ced9214648a436da63f445539d76ddf3e38c23e Mon Sep 17 00:00:00 2001 From: Noah Talerman Date: Wed, 11 Nov 2020 16:23:39 -0800 Subject: [PATCH 4/6] Added additional_info_filters description and link to configuration example with additional information. --- docs/api/rest-endpoints.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/api/rest-endpoints.md b/docs/api/rest-endpoints.md index 72640ccc12e2..c16017f6bbcb 100644 --- a/docs/api/rest-endpoints.md +++ b/docs/api/rest-endpoints.md @@ -8,12 +8,12 @@ Parameters -| Name | Type | In | Description | -|-------------------------|---------|-------|--------------------------------------------------------------------------| -| page | integer | query | Page number of the results to fetch. | -| per_page | integer | query | Results per page. | -| order_key | string | query | What to order results by. Can be any column in the hosts table. | -| additional_info_filters | string | query | TODO | +| Name | Type | In | Description | +|-------------------------|---------|-------|------------------------------------------------------------------------------------------| +| page | integer | query | Page number of the results to fetch. | +| per_page | integer | query | Results per page. | +| order_key | string | query | What to order results by. Can be any column in the hosts table. | +| additional_info_filters | string | query | A comma delimited list of fields to include in each host's additional information object. See [Fleet Configuration Options](https://github.com/fleetdm/fleet/blob/master/docs/cli/file-format.md#fleet-configuration-options) for an example configuration with hosts' additional information.| Example From 69cf03c52d08b4acedba89319ab564833c0f2adc Mon Sep 17 00:00:00 2001 From: Noah Talerman Date: Thu, 12 Nov 2020 09:23:12 -0800 Subject: [PATCH 5/6] Added query parameter to /hosts endpoint table. --- docs/api/rest-endpoints.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/api/rest-endpoints.md b/docs/api/rest-endpoints.md index c16017f6bbcb..faf2892acf3f 100644 --- a/docs/api/rest-endpoints.md +++ b/docs/api/rest-endpoints.md @@ -13,6 +13,7 @@ Parameters | page | integer | query | Page number of the results to fetch. | | per_page | integer | query | Results per page. | | order_key | string | query | What to order results by. Can be any column in the hosts table. | +| status | string | query | Indicates the status of the hosts to return. Can either be `new`, `online`, `offline`, or `mia`.| | additional_info_filters | string | query | A comma delimited list of fields to include in each host's additional information object. See [Fleet Configuration Options](https://github.com/fleetdm/fleet/blob/master/docs/cli/file-format.md#fleet-configuration-options) for an example configuration with hosts' additional information.| Example From ee9dba6655d70bd992d010ce6224a99588d0472a Mon Sep 17 00:00:00 2001 From: noahtalerman <47070608+noahtalerman@users.noreply.github.com> Date: Thu, 12 Nov 2020 12:13:33 -0800 Subject: [PATCH 6/6] Update copy in rest-endpoint.md Added a hyphen to "comma-delimited." --- docs/api/rest-endpoints.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/api/rest-endpoints.md b/docs/api/rest-endpoints.md index faf2892acf3f..8e78292dc4f6 100644 --- a/docs/api/rest-endpoints.md +++ b/docs/api/rest-endpoints.md @@ -14,7 +14,7 @@ Parameters | per_page | integer | query | Results per page. | | order_key | string | query | What to order results by. Can be any column in the hosts table. | | status | string | query | Indicates the status of the hosts to return. Can either be `new`, `online`, `offline`, or `mia`.| -| additional_info_filters | string | query | A comma delimited list of fields to include in each host's additional information object. See [Fleet Configuration Options](https://github.com/fleetdm/fleet/blob/master/docs/cli/file-format.md#fleet-configuration-options) for an example configuration with hosts' additional information.| +| additional_info_filters | string | query | A comma-delimited list of fields to include in each host's additional information object. See [Fleet Configuration Options](https://github.com/fleetdm/fleet/blob/master/docs/cli/file-format.md#fleet-configuration-options) for an example configuration with hosts' additional information.| Example @@ -99,4 +99,4 @@ Example }, ] } -``` \ No newline at end of file +```