github-mirrors/kibana
1
0
Fork 0
mirror of https://github.com/elastic/kibana.git synced 2025-04-24 01:38:56 -04:00
Code Issues Projects Releases Packages Wiki Activity

[8.17] Improves Lists API docs content (#192504) (#204712)

Browse source 
# Backport

This will backport the following commits from `main` to `8.17`:
- [Improves Lists API docs content
(#192504)](https://github.com/elastic/kibana/pull/192504)

<!--- Backport version: 8.9.8 -->

### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sqren/backport)

<!--BACKPORT
[{"author":{"name":"natasha-moore-elastic","email":"137783811+natasha-moore-elastic@users.noreply.github.com"},"sourceCommit":{"committedDate":"2024-09-17T11:24:07Z","message":"Improves
Lists API docs content (#192504)\n\n## Summary\r\n\r\nResolves
https://github.com/elastic/security-docs-internal/issues/32
by\r\nimproving the Lists API docs content. Adds missing and improves
existing\r\noperation summaries and operation descriptions to adhere to
our
[OAS\r\nstandards](450494532/API+reference+docs).\r\n\r\nNote:
Couldn’t add description for the GET /api/lists/privileges\r\noperation,
since it's not documented in [ESS
API\r\ndocs](https://www.elastic.co/guide/en/security/8.15/security-apis.html).\r\n\r\n---------\r\n\r\nCo-authored-by:
kibanamachine
<42973632+kibanamachine@users.noreply.github.com>","sha":"5c5897966ab0d6caaba64d943d91d0485dde16f2","branchLabelMapping":{"^v9.0.0$":"main","^v8.16.0$":"8.x","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["release_note:skip","backport:skip","v9.0.0","docs","Team:Detections
and Resp","Team: SecuritySolution","APIDocs","Team:Detection Rule
Management","Team:Detection
Engine"],"number":192504,"url":"https://github.com/elastic/kibana/pull/192504","mergeCommit":{"message":"Improves
Lists API docs content (#192504)\n\n## Summary\r\n\r\nResolves
https://github.com/elastic/security-docs-internal/issues/32
by\r\nimproving the Lists API docs content. Adds missing and improves
existing\r\noperation summaries and operation descriptions to adhere to
our
[OAS\r\nstandards](450494532/API+reference+docs).\r\n\r\nNote:
Couldn’t add description for the GET /api/lists/privileges\r\noperation,
since it's not documented in [ESS
API\r\ndocs](https://www.elastic.co/guide/en/security/8.15/security-apis.html).\r\n\r\n---------\r\n\r\nCo-authored-by:
kibanamachine
<42973632+kibanamachine@users.noreply.github.com>","sha":"5c5897966ab0d6caaba64d943d91d0485dde16f2"}},"sourceBranch":"main","suggestedTargetBranches":[],"targetPullRequestStates":[{"branch":"main","label":"v9.0.0","labelRegex":"^v9.0.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/192504","number":192504,"mergeCommit":{"message":"Improves
Lists API docs content (#192504)\n\n## Summary\r\n\r\nResolves
https://github.com/elastic/security-docs-internal/issues/32
by\r\nimproving the Lists API docs content. Adds missing and improves
existing\r\noperation summaries and operation descriptions to adhere to
our
[OAS\r\nstandards](450494532/API+reference+docs).\r\n\r\nNote:
Couldn’t add description for the GET /api/lists/privileges\r\noperation,
since it's not documented in [ESS
API\r\ndocs](https://www.elastic.co/guide/en/security/8.15/security-apis.html).\r\n\r\n---------\r\n\r\nCo-authored-by:
kibanamachine
<42973632+kibanamachine@users.noreply.github.com>","sha":"5c5897966ab0d6caaba64d943d91d0485dde16f2"}}]}]
BACKPORT-->

---------

Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>
This commit is contained in:
natasha-moore-elastic 2024-12-18 18:12:54 +00:00 • committed by GitHub
parent c2057c856f
commit 471a3d17e4
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
23 changed files with 344 additions and 86 deletions
Download patch file Download diff file Expand all files Collapse all files

69
oas_docs/output/kibana.yaml
View file

@ -16095,6 +16095,10 @@ paths:
- Fleet uninstall tokens
/api/lists:
delete:
description: |
Delete a list using the list ID.
> info
> When you delete a list, all of its list items are also deleted.
operationId: DeleteList
parameters:
- description: List's `id` value
@ -16154,10 +16158,11 @@ paths:
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: Internal server error response
summary: Deletes a list
summary: Delete a list
tags:
- Security Lists API
get:
description: Get the details of a list using the list ID.
operationId: ReadList
parameters:
- description: List's `id` value
@ -16205,10 +16210,11 @@ paths:
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: Internal server error response
summary: Retrieves a list using its id field
summary: Get list details
tags:
- Security Lists API
patch:
description: Update specific fields of an existing list using the list ID.
operationId: PatchList
requestBody:
content:
@ -16272,10 +16278,11 @@ paths:
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: Internal server error response
summary: Patches a list
summary: Patch a list
tags:
- Security Lists API
post:
description: Create a new list.
operationId: CreateList
requestBody:
content:
@ -16346,10 +16353,14 @@ paths:
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: Internal server error response
summary: Creates a list
summary: Create a list
tags:
- Security Lists API
put:
description: |
Update a list using the list ID. The original list is replaced, and all unspecified fields are deleted.
> info
> You cannot modify the `id` value.
operationId: UpdateList
requestBody:
content:
@ -16415,11 +16426,12 @@ paths:
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: Internal server error response
summary: Updates a list
summary: Update a list
tags:
- Security Lists API
/api/lists/_find:
get:
description: Get a paginated subset of lists. By default, the first page is returned, with 20 results per page.
operationId: FindLists
parameters:
- description: The page number to return
@ -16521,11 +16533,12 @@ paths:
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: Internal server error response
summary: Finds lists
summary: Get lists
tags:
- Security Lists API
/api/lists/index:
delete:
description: Delete the `.lists` and `.items` data streams.
operationId: DeleteListIndex
responses:
'200':
@ -16571,10 +16584,11 @@ paths:
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: Internal server error response
summary: Deletes list data streams
summary: Delete list data streams
tags:
- Security Lists API
get:
description: Verify that `.lists` and `.items` data streams exist.
operationId: ReadListIndex
responses:
'200':
@ -16623,10 +16637,11 @@ paths:
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: Internal server error response
summary: Get list data stream existence status
summary: Get status of list data streams
tags:
- Security Lists API
post:
description: Create `.lists` and `.items` data streams in the relevant space.
operationId: CreateListIndex
responses:
'200':
@ -16672,11 +16687,12 @@ paths:
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: Internal server error response
summary: Creates necessary list data streams
summary: Create list data streams
tags:
- Security Lists API
/api/lists/items:
delete:
description: Delete a list item using its `id`, or its `list_id` and `value` fields.
operationId: DeleteListItem
parameters:
- description: Required if `list_id` and `value` are not specified
@ -16751,10 +16767,11 @@ paths:
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: Internal server error response
summary: Deletes a list item
summary: Delete a list item
tags:
- Security Lists API
get:
description: Get the details of a list item.
operationId: ReadListItem
parameters:
- description: Required if `list_id` and `value` are not specified
@ -16818,10 +16835,11 @@ paths:
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: Internal server error response
summary: Gets a list item
summary: Get a list item
tags:
- Security Lists API
patch:
description: Update specific fields of an existing list item using the list item ID.
operationId: PatchListItem
requestBody:
content:
@ -16887,10 +16905,16 @@ paths:
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: Internal server error response
summary: Patches a list item
summary: Patch a list item
tags:
- Security Lists API
post:
description: |
Create a list item and associate it with the specified list.
All list items in the same list must be the same type. For example, each list item in an `ip` list must define a specific IP address.
> info
> Before creating a list item, you must create a list.
operationId: CreateListItem
requestBody:
content:
@ -16957,10 +16981,14 @@ paths:
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: Internal server error response
summary: Creates a list item
summary: Create a list item
tags:
- Security Lists API
put:
description: |
Update a list item using the list item ID. The original list item is replaced, and all unspecified fields are deleted.
> info
> You cannot modify the `id` value.
operationId: UpdateListItem
requestBody:
content:
@ -17020,12 +17048,12 @@ paths:
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: Internal server error response
summary: Updates a list item
summary: Update a list item
tags:
- Security Lists API
/api/lists/items/_export:
post:
description: Exports list item values from the specified list
description: Export list item values from the specified list.
operationId: ExportListItems
parameters:
- description: List's id to export
@ -17075,11 +17103,12 @@ paths:
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: Internal server error response
summary: Exports list items
summary: Export list items
tags:
- Security Lists API
/api/lists/items/_find:
get:
description: Get all list items in the specified list.
operationId: FindListItems
parameters:
- description: List's id
@ -17187,13 +17216,13 @@ paths:
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: Internal server error response
summary: Finds list items
summary: Get list items
tags:
- Security Lists API
/api/lists/items/_import:
post:
description: |
Imports a list of items from a `.txt` or `.csv` file. The maximum file size is 9 million bytes.
Import list items from a TXT or CSV file. The maximum file size is 9 million bytes.
You can import items to a new or existing list.
operationId: ImportListItems
@ -17286,7 +17315,7 @@ paths:
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: Internal server error response
summary: Imports list items
summary: Import list items
tags:
- Security Lists API
/api/lists/privileges:
@ -17336,7 +17365,7 @@ paths:
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: Internal server error response
summary: Gets list privileges
summary: Get list privileges
tags:
- Security Lists API
/api/ml/saved_objects/sync:

3
packages/kbn-securitysolution-lists-common/api/create_list/create_list.schema.yaml
View file

@ -8,7 +8,8 @@ paths:
x-labels: [serverless, ess]
operationId: CreateList
x-codegen-enabled: true
summary: Creates a list
summary: Create a list
description: Create a new list.
requestBody:
description: List's properties
required: true

3
packages/kbn-securitysolution-lists-common/api/create_list_index/create_list_index.schema.yaml
View file

@ -8,7 +8,8 @@ paths:
x-labels: [serverless, ess]
operationId: CreateListIndex
x-codegen-enabled: true
summary: Creates necessary list data streams
summary: Create list data streams
description: Create `.lists` and `.items` data streams in the relevant space.
responses:
200:
description: Successful response

8
packages/kbn-securitysolution-lists-common/api/create_list_item/create_list_item.schema.yaml
View file

@ -8,7 +8,13 @@ paths:
x-labels: [serverless, ess]
operationId: CreateListItem
x-codegen-enabled: true
summary: Creates a list item
summary: Create a list item
description: |
Create a list item and associate it with the specified list.
All list items in the same list must be the same type. For example, each list item in an `ip` list must define a specific IP address.
> info
> Before creating a list item, you must create a list.
requestBody:
description: List item's properties
required: true

6
packages/kbn-securitysolution-lists-common/api/delete_list/delete_list.schema.yaml
View file

@ -8,7 +8,11 @@ paths:
x-labels: [serverless, ess]
operationId: DeleteList
x-codegen-enabled: true
summary: Deletes a list
summary: Delete a list
description: |
Delete a list using the list ID.
> info
> When you delete a list, all of its list items are also deleted.
parameters:
- name: id
in: query

3
packages/kbn-securitysolution-lists-common/api/delete_list_index/delete_list_index.schema.yaml
View file

@ -8,7 +8,8 @@ paths:
x-labels: [serverless, ess]
operationId: DeleteListIndex
x-codegen-enabled: true
summary: Deletes list data streams
summary: Delete list data streams
description: Delete the `.lists` and `.items` data streams.
responses:
200:
description: Successful response

3
packages/kbn-securitysolution-lists-common/api/delete_list_item/delete_list_item.schema.yaml
View file

@ -8,7 +8,8 @@ paths:
x-labels: [serverless, ess]
operationId: DeleteListItem
x-codegen-enabled: true
summary: Deletes a list item
summary: Delete a list item
description: Delete a list item using its `id`, or its `list_id` and `value` fields.
parameters:
- name: id
in: query

4
packages/kbn-securitysolution-lists-common/api/export_list_items/export_list_items.schema.yaml
View file

@ -8,8 +8,8 @@ paths:
x-labels: [serverless, ess]
operationId: ExportListItems
x-codegen-enabled: true
summary: Exports list items
description: Exports list item values from the specified list
summary: Export list items
description: Export list item values from the specified list.
parameters:
- name: list_id
in: query

3
packages/kbn-securitysolution-lists-common/api/find_list_items/find_list_items.schema.yaml
View file

@ -8,7 +8,8 @@ paths:
x-labels: [serverless, ess]
operationId: FindListItems
x-codegen-enabled: true
summary: Finds list items
summary: Get list items
description: Get all list items in the specified list.
parameters:
- name: list_id
in: query

3
packages/kbn-securitysolution-lists-common/api/find_lists/find_lists.schema.yaml
View file

@ -8,7 +8,8 @@ paths:
x-labels: [serverless, ess]
operationId: FindLists
x-codegen-enabled: true
summary: Finds lists
summary: Get lists
description: Get a paginated subset of lists. By default, the first page is returned, with 20 results per page.
parameters:
- name: page
in: query

4
packages/kbn-securitysolution-lists-common/api/import_list_items/import_list_items.schema.yaml
View file

@ -8,9 +8,9 @@ paths:
x-labels: [serverless, ess]
operationId: ImportListItems
x-codegen-enabled: true
summary: Imports list items
summary: Import list items
description: |
Imports a list of items from a `.txt` or `.csv` file. The maximum file size is 9 million bytes.
Import list items from a TXT or CSV file. The maximum file size is 9 million bytes.
You can import items to a new or existing list.
requestBody:

3
packages/kbn-securitysolution-lists-common/api/patch_list/patch_list.schema.yaml
View file

@ -8,7 +8,8 @@ paths:
x-labels: [serverless, ess]
operationId: PatchList
x-codegen-enabled: true
summary: Patches a list
summary: Patch a list
description: Update specific fields of an existing list using the list ID.
requestBody:
description: List's properties
required: true

3
packages/kbn-securitysolution-lists-common/api/patch_list_item/patch_list_item.schema.yaml
View file

@ -8,7 +8,8 @@ paths:
x-labels: [serverless, ess]
operationId: PatchListItem
x-codegen-enabled: true
summary: Patches a list item
summary: Patch a list item
description: Update specific fields of an existing list item using the list item ID.
requestBody:
description: List item's properties
required: true

63
packages/kbn-securitysolution-lists-common/api/quickstart_client.gen.ts
View file

@ -77,6 +77,9 @@ export class Client {
this.kbnClient = options.kbnClient;
this.log = options.log;
}
/**
* Create a new list.
*/
async createList(props: CreateListProps) {
this.log.info(`${new Date().toISOString()} Calling API CreateList`);
return this.kbnClient
@ -90,6 +93,9 @@ export class Client {
})
.catch(catchAxiosErrorFormatAndThrow);
}
/**
* Create `.lists` and `.items` data streams in the relevant space.
*/
async createListIndex() {
this.log.info(`${new Date().toISOString()} Calling API CreateListIndex`);
return this.kbnClient
@ -102,6 +108,14 @@ export class Client {
})
.catch(catchAxiosErrorFormatAndThrow);
}
/**
* Create a list item and associate it with the specified list.
All list items in the same list must be the same type. For example, each list item in an `ip` list must define a specific IP address.
> info
> Before creating a list item, you must create a list.
*/
async createListItem(props: CreateListItemProps) {
this.log.info(`${new Date().toISOString()} Calling API CreateListItem`);
return this.kbnClient
@ -115,6 +129,12 @@ export class Client {
})
.catch(catchAxiosErrorFormatAndThrow);
}
/**
* Delete a list using the list ID.
> info
> When you delete a list, all of its list items are also deleted.
*/
async deleteList(props: DeleteListProps) {
this.log.info(`${new Date().toISOString()} Calling API DeleteList`);
return this.kbnClient
@ -129,6 +149,9 @@ export class Client {
})
.catch(catchAxiosErrorFormatAndThrow);
}
/**
* Delete the `.lists` and `.items` data streams.
*/
async deleteListIndex() {
this.log.info(`${new Date().toISOString()} Calling API DeleteListIndex`);
return this.kbnClient
@ -141,6 +164,9 @@ export class Client {
})
.catch(catchAxiosErrorFormatAndThrow);
}
/**
* Delete a list item using its `id`, or its `list_id` and `value` fields.
*/
async deleteListItem(props: DeleteListItemProps) {
this.log.info(`${new Date().toISOString()} Calling API DeleteListItem`);
return this.kbnClient
@ -156,7 +182,7 @@ export class Client {
.catch(catchAxiosErrorFormatAndThrow);
}
/**
* Exports list item values from the specified list
* Export list item values from the specified list.
*/
async exportListItems(props: ExportListItemsProps) {
this.log.info(`${new Date().toISOString()} Calling API ExportListItems`);
@ -172,6 +198,9 @@ export class Client {
})
.catch(catchAxiosErrorFormatAndThrow);
}
/**
* Get all list items in the specified list.
*/
async findListItems(props: FindListItemsProps) {
this.log.info(`${new Date().toISOString()} Calling API FindListItems`);
return this.kbnClient
@ -186,6 +215,9 @@ export class Client {
})
.catch(catchAxiosErrorFormatAndThrow);
}
/**
* Get a paginated subset of lists. By default, the first page is returned, with 20 results per page.
*/
async findLists(props: FindListsProps) {
this.log.info(`${new Date().toISOString()} Calling API FindLists`);
return this.kbnClient
@ -201,7 +233,7 @@ export class Client {
.catch(catchAxiosErrorFormatAndThrow);
}
/**
* Imports a list of items from a `.txt` or `.csv` file. The maximum file size is 9 million bytes.
* Import list items from a TXT or CSV file. The maximum file size is 9 million bytes.
You can import items to a new or existing list.
@ -220,6 +252,9 @@ You can import items to a new or existing list.
})
.catch(catchAxiosErrorFormatAndThrow);
}
/**
* Update specific fields of an existing list using the list ID.
*/
async patchList(props: PatchListProps) {
this.log.info(`${new Date().toISOString()} Calling API PatchList`);
return this.kbnClient
@ -233,6 +268,9 @@ You can import items to a new or existing list.
})
.catch(catchAxiosErrorFormatAndThrow);
}
/**
* Update specific fields of an existing list item using the list item ID.
*/
async patchListItem(props: PatchListItemProps) {
this.log.info(`${new Date().toISOString()} Calling API PatchListItem`);
return this.kbnClient
@ -246,6 +284,9 @@ You can import items to a new or existing list.
})
.catch(catchAxiosErrorFormatAndThrow);
}
/**
* Get the details of a list using the list ID.
*/
async readList(props: ReadListProps) {
this.log.info(`${new Date().toISOString()} Calling API ReadList`);
return this.kbnClient
@ -260,6 +301,9 @@ You can import items to a new or existing list.
})
.catch(catchAxiosErrorFormatAndThrow);
}
/**
* Verify that `.lists` and `.items` data streams exist.
*/
async readListIndex() {
this.log.info(`${new Date().toISOString()} Calling API ReadListIndex`);
return this.kbnClient
@ -272,6 +316,9 @@ You can import items to a new or existing list.
})
.catch(catchAxiosErrorFormatAndThrow);
}
/**
* Get the details of a list item.
*/
async readListItem(props: ReadListItemProps) {
this.log.info(`${new Date().toISOString()} Calling API ReadListItem`);
return this.kbnClient
@ -298,6 +345,12 @@ You can import items to a new or existing list.
})
.catch(catchAxiosErrorFormatAndThrow);
}
/**
* Update a list using the list ID. The original list is replaced, and all unspecified fields are deleted.
> info
> You cannot modify the `id` value.
*/
async updateList(props: UpdateListProps) {
this.log.info(`${new Date().toISOString()} Calling API UpdateList`);
return this.kbnClient
@ -311,6 +364,12 @@ You can import items to a new or existing list.
})
.catch(catchAxiosErrorFormatAndThrow);
}
/**
* Update a list item using the list item ID. The original list item is replaced, and all unspecified fields are deleted.
> info
> You cannot modify the `id` value.
*/
async updateListItem(props: UpdateListItemProps) {
this.log.info(`${new Date().toISOString()} Calling API UpdateListItem`);
return this.kbnClient

3
packages/kbn-securitysolution-lists-common/api/read_list/read_list.schema.yaml
View file

@ -8,7 +8,8 @@ paths:
x-labels: [serverless, ess]
operationId: ReadList
x-codegen-enabled: true
summary: Retrieves a list using its id field
summary: Get list details
description: Get the details of a list using the list ID.
parameters:
- name: id
in: query

3
packages/kbn-securitysolution-lists-common/api/read_list_index/read_list_index.schema.yaml
View file

@ -8,7 +8,8 @@ paths:
x-labels: [serverless, ess]
operationId: ReadListIndex
x-codegen-enabled: true
summary: Get list data stream existence status
summary: Get status of list data streams
description: Verify that `.lists` and `.items` data streams exist.
responses:
200:
description: Successful response

3
packages/kbn-securitysolution-lists-common/api/read_list_item/read_list_item.schema.yaml
View file

@ -8,7 +8,8 @@ paths:
x-labels: [serverless, ess]
operationId: ReadListItem
x-codegen-enabled: true
summary: Gets a list item
summary: Get a list item
description: Get the details of a list item.
parameters:
- name: id
in: query

2
packages/kbn-securitysolution-lists-common/api/read_list_privileges/read_list_privileges.schema.yaml
View file

@ -8,7 +8,7 @@ paths:
x-labels: [serverless, ess]
operationId: ReadListPrivileges
x-codegen-enabled: true
summary: Gets list privileges
summary: Get list privileges
responses:
200:
description: Successful response

6
packages/kbn-securitysolution-lists-common/api/update_list/update_list.schema.yaml
View file

@ -8,7 +8,11 @@ paths:
x-labels: [serverless, ess]
operationId: UpdateList
x-codegen-enabled: true
summary: Updates a list
summary: Update a list
description: |
Update a list using the list ID. The original list is replaced, and all unspecified fields are deleted.
> info
> You cannot modify the `id` value.
requestBody:
description: List's properties
required: true

6
packages/kbn-securitysolution-lists-common/api/update_list_item/update_list_item.schema.yaml
View file

@ -8,7 +8,11 @@ paths:
x-labels: [serverless, ess]
operationId: UpdateListItem
x-codegen-enabled: true
summary: Updates a list item
summary: Update a list item
description: |
Update a list item using the list item ID. The original list item is replaced, and all unspecified fields are deleted.
> info
> You cannot modify the `id` value.
requestBody:
description: List item's properties
required: true

83
packages/kbn-securitysolution-lists-common/docs/openapi/ess/security_solution_lists_api_2023_10_31.bundled.schema.yaml
View file

@ -13,6 +13,10 @@ servers:
paths:
/api/lists:
delete:
description: |
Delete a list using the list ID.
> info
> When you delete a list, all of its list items are also deleted.
operationId: DeleteList
parameters:
- description: List's `id` value
@ -72,10 +76,11 @@ paths:
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
summary: Deletes a list
summary: Delete a list
tags:
- Security Lists API
get:
description: Get the details of a list using the list ID.
operationId: ReadList
parameters:
- description: List's `id` value
@ -123,10 +128,11 @@ paths:
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
summary: Retrieves a list using its id field
summary: Get list details
tags:
- Security Lists API
patch:
description: Update specific fields of an existing list using the list ID.
operationId: PatchList
requestBody:
content:
@ -190,10 +196,11 @@ paths:
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
summary: Patches a list
summary: Patch a list
tags:
- Security Lists API
post:
description: Create a new list.
operationId: CreateList
requestBody:
content:
@ -264,10 +271,17 @@ paths:
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
summary: Creates a list
summary: Create a list
tags:
- Security Lists API
put:
description: >
Update a list using the list ID. The original list is replaced, and all
unspecified fields are deleted.
> info
> You cannot modify the `id` value.
operationId: UpdateList
requestBody:
content:
@ -333,11 +347,14 @@ paths:
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
summary: Updates a list
summary: Update a list
tags:
- Security Lists API
/api/lists/_find:
get:
description: >-
Get a paginated subset of lists. By default, the first page is returned,
with 20 results per page.
operationId: FindLists
parameters:
- description: The page number to return
@ -446,11 +463,12 @@ paths:
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
summary: Finds lists
summary: Get lists
tags:
- Security Lists API
/api/lists/index:
delete:
description: Delete the `.lists` and `.items` data streams.
operationId: DeleteListIndex
responses:
'200':
@ -496,10 +514,11 @@ paths:
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
summary: Deletes list data streams
summary: Delete list data streams
tags:
- Security Lists API
get:
description: Verify that `.lists` and `.items` data streams exist.
operationId: ReadListIndex
responses:
'200':
@ -548,10 +567,11 @@ paths:
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
summary: Get list data stream existence status
summary: Get status of list data streams
tags:
- Security Lists API
post:
description: Create `.lists` and `.items` data streams in the relevant space.
operationId: CreateListIndex
responses:
'200':
@ -597,11 +617,12 @@ paths:
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
summary: Creates necessary list data streams
summary: Create list data streams
tags:
- Security Lists API
/api/lists/items:
delete:
description: 'Delete a list item using its `id`, or its `list_id` and `value` fields.'
operationId: DeleteListItem
parameters:
- description: Required if `list_id` and `value` are not specified
@ -678,10 +699,11 @@ paths:
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
summary: Deletes a list item
summary: Delete a list item
tags:
- Security Lists API
get:
description: Get the details of a list item.
operationId: ReadListItem
parameters:
- description: Required if `list_id` and `value` are not specified
@ -745,10 +767,11 @@ paths:
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
summary: Gets a list item
summary: Get a list item
tags:
- Security Lists API
patch:
description: Update specific fields of an existing list item using the list item ID.
operationId: PatchListItem
requestBody:
content:
@ -816,10 +839,20 @@ paths:
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
summary: Patches a list item
summary: Patch a list item
tags:
- Security Lists API
post:
description: >
Create a list item and associate it with the specified list.
All list items in the same list must be the same type. For example, each
list item in an `ip` list must define a specific IP address.
> info
> Before creating a list item, you must create a list.
operationId: CreateListItem
requestBody:
content:
@ -888,10 +921,17 @@ paths:
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
summary: Creates a list item
summary: Create a list item
tags:
- Security Lists API
put:
description: >
Update a list item using the list item ID. The original list item is
replaced, and all unspecified fields are deleted.
> info
> You cannot modify the `id` value.
operationId: UpdateListItem
requestBody:
content:
@ -951,12 +991,12 @@ paths:
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
summary: Updates a list item
summary: Update a list item
tags:
- Security Lists API
/api/lists/items/_export:
post:
description: Exports list item values from the specified list
description: Export list item values from the specified list.
operationId: ExportListItems
parameters:
- description: List's id to export
@ -1006,11 +1046,12 @@ paths:
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
summary: Exports list items
summary: Export list items
tags:
- Security Lists API
/api/lists/items/_find:
get:
description: Get all list items in the specified list.
operationId: FindListItems
parameters:
- description: List's id
@ -1125,14 +1166,14 @@ paths:
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
summary: Finds list items
summary: Get list items
tags:
- Security Lists API
/api/lists/items/_import:
post:
description: >
Imports a list of items from a `.txt` or `.csv` file. The maximum file
size is 9 million bytes.
Import list items from a TXT or CSV file. The maximum file size is 9
million bytes.
You can import items to a new or existing list.
@ -1232,7 +1273,7 @@ paths:
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
summary: Imports list items
summary: Import list items
tags:
- Security Lists API
/api/lists/privileges:
@ -1282,7 +1323,7 @@ paths:
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
summary: Gets list privileges
summary: Get list privileges
tags:
- Security Lists API
components:

83
packages/kbn-securitysolution-lists-common/docs/openapi/serverless/security_solution_lists_api_2023_10_31.bundled.schema.yaml
View file

@ -13,6 +13,10 @@ servers:
paths:
/api/lists:
delete:
description: |
Delete a list using the list ID.
> info
> When you delete a list, all of its list items are also deleted.
operationId: DeleteList
parameters:
- description: List's `id` value
@ -72,10 +76,11 @@ paths:
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
summary: Deletes a list
summary: Delete a list
tags:
- Security Lists API
get:
description: Get the details of a list using the list ID.
operationId: ReadList
parameters:
- description: List's `id` value
@ -123,10 +128,11 @@ paths:
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
summary: Retrieves a list using its id field
summary: Get list details
tags:
- Security Lists API
patch:
description: Update specific fields of an existing list using the list ID.
operationId: PatchList
requestBody:
content:
@ -190,10 +196,11 @@ paths:
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
summary: Patches a list
summary: Patch a list
tags:
- Security Lists API
post:
description: Create a new list.
operationId: CreateList
requestBody:
content:
@ -264,10 +271,17 @@ paths:
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
summary: Creates a list
summary: Create a list
tags:
- Security Lists API
put:
description: >
Update a list using the list ID. The original list is replaced, and all
unspecified fields are deleted.
> info
> You cannot modify the `id` value.
operationId: UpdateList
requestBody:
content:
@ -333,11 +347,14 @@ paths:
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
summary: Updates a list
summary: Update a list
tags:
- Security Lists API
/api/lists/_find:
get:
description: >-
Get a paginated subset of lists. By default, the first page is returned,
with 20 results per page.
operationId: FindLists
parameters:
- description: The page number to return
@ -446,11 +463,12 @@ paths:
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
summary: Finds lists
summary: Get lists
tags:
- Security Lists API
/api/lists/index:
delete:
description: Delete the `.lists` and `.items` data streams.
operationId: DeleteListIndex
responses:
'200':
@ -496,10 +514,11 @@ paths:
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
summary: Deletes list data streams
summary: Delete list data streams
tags:
- Security Lists API
get:
description: Verify that `.lists` and `.items` data streams exist.
operationId: ReadListIndex
responses:
'200':
@ -548,10 +567,11 @@ paths:
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
summary: Get list data stream existence status
summary: Get status of list data streams
tags:
- Security Lists API
post:
description: Create `.lists` and `.items` data streams in the relevant space.
operationId: CreateListIndex
responses:
'200':
@ -597,11 +617,12 @@ paths:
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
summary: Creates necessary list data streams
summary: Create list data streams
tags:
- Security Lists API
/api/lists/items:
delete:
description: 'Delete a list item using its `id`, or its `list_id` and `value` fields.'
operationId: DeleteListItem
parameters:
- description: Required if `list_id` and `value` are not specified
@ -678,10 +699,11 @@ paths:
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
summary: Deletes a list item
summary: Delete a list item
tags:
- Security Lists API
get:
description: Get the details of a list item.
operationId: ReadListItem
parameters:
- description: Required if `list_id` and `value` are not specified
@ -745,10 +767,11 @@ paths:
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
summary: Gets a list item
summary: Get a list item
tags:
- Security Lists API
patch:
description: Update specific fields of an existing list item using the list item ID.
operationId: PatchListItem
requestBody:
content:
@ -816,10 +839,20 @@ paths:
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
summary: Patches a list item
summary: Patch a list item
tags:
- Security Lists API
post:
description: >
Create a list item and associate it with the specified list.
All list items in the same list must be the same type. For example, each
list item in an `ip` list must define a specific IP address.
> info
> Before creating a list item, you must create a list.
operationId: CreateListItem
requestBody:
content:
@ -888,10 +921,17 @@ paths:
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
summary: Creates a list item
summary: Create a list item
tags:
- Security Lists API
put:
description: >
Update a list item using the list item ID. The original list item is
replaced, and all unspecified fields are deleted.
> info
> You cannot modify the `id` value.
operationId: UpdateListItem
requestBody:
content:
@ -951,12 +991,12 @@ paths:
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
summary: Updates a list item
summary: Update a list item
tags:
- Security Lists API
/api/lists/items/_export:
post:
description: Exports list item values from the specified list
description: Export list item values from the specified list.
operationId: ExportListItems
parameters:
- description: List's id to export
@ -1006,11 +1046,12 @@ paths:
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
summary: Exports list items
summary: Export list items
tags:
- Security Lists API
/api/lists/items/_find:
get:
description: Get all list items in the specified list.
operationId: FindListItems
parameters:
- description: List's id
@ -1125,14 +1166,14 @@ paths:
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
summary: Finds list items
summary: Get list items
tags:
- Security Lists API
/api/lists/items/_import:
post:
description: >
Imports a list of items from a `.txt` or `.csv` file. The maximum file
size is 9 million bytes.
Import list items from a TXT or CSV file. The maximum file size is 9
million bytes.
You can import items to a new or existing list.
@ -1232,7 +1273,7 @@ paths:
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
summary: Imports list items
summary: Import list items
tags:
- Security Lists API
/api/lists/privileges:
@ -1282,7 +1323,7 @@ paths:
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
summary: Gets list privileges
summary: Get list privileges
tags:
- Security Lists API
components:

63
x-pack/test/api_integration/services/security_solution_lists_api.gen.ts
View file

@ -40,6 +40,9 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext)
const supertest = getService('supertest');
return {
/**
* Create a new list.
*/
createList(props: CreateListProps, kibanaSpace: string = 'default') {
return supertest
.post(routeWithNamespace('/api/lists', kibanaSpace))
@ -48,6 +51,9 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext)
.set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
.send(props.body as object);
},
/**
* Create `.lists` and `.items` data streams in the relevant space.
*/
createListIndex(kibanaSpace: string = 'default') {
return supertest
.post(routeWithNamespace('/api/lists/index', kibanaSpace))
@ -55,6 +61,14 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext)
.set(ELASTIC_HTTP_VERSION_HEADER, '2023-10-31')
.set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana');
},
/**
* Create a list item and associate it with the specified list.
All list items in the same list must be the same type. For example, each list item in an `ip` list must define a specific IP address.
> info
> Before creating a list item, you must create a list.
*/
createListItem(props: CreateListItemProps, kibanaSpace: string = 'default') {
return supertest
.post(routeWithNamespace('/api/lists/items', kibanaSpace))
@ -63,6 +77,12 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext)
.set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
.send(props.body as object);
},
/**
* Delete a list using the list ID.
> info
> When you delete a list, all of its list items are also deleted.
*/
deleteList(props: DeleteListProps, kibanaSpace: string = 'default') {
return supertest
.delete(routeWithNamespace('/api/lists', kibanaSpace))
@ -71,6 +91,9 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext)
.set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
.query(props.query);
},
/**
* Delete the `.lists` and `.items` data streams.
*/
deleteListIndex(kibanaSpace: string = 'default') {
return supertest
.delete(routeWithNamespace('/api/lists/index', kibanaSpace))
@ -78,6 +101,9 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext)
.set(ELASTIC_HTTP_VERSION_HEADER, '2023-10-31')
.set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana');
},
/**
* Delete a list item using its `id`, or its `list_id` and `value` fields.
*/
deleteListItem(props: DeleteListItemProps, kibanaSpace: string = 'default') {
return supertest
.delete(routeWithNamespace('/api/lists/items', kibanaSpace))
@ -87,7 +113,7 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext)
.query(props.query);
},
/**
* Exports list item values from the specified list
* Export list item values from the specified list.
*/
exportListItems(props: ExportListItemsProps, kibanaSpace: string = 'default') {
return supertest
@ -97,6 +123,9 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext)
.set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
.query(props.query);
},
/**
* Get all list items in the specified list.
*/
findListItems(props: FindListItemsProps, kibanaSpace: string = 'default') {
return supertest
.get(routeWithNamespace('/api/lists/items/_find', kibanaSpace))
@ -105,6 +134,9 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext)
.set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
.query(props.query);
},
/**
* Get a paginated subset of lists. By default, the first page is returned, with 20 results per page.
*/
findLists(props: FindListsProps, kibanaSpace: string = 'default') {
return supertest
.get(routeWithNamespace('/api/lists/_find', kibanaSpace))
@ -114,7 +146,7 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext)
.query(props.query);
},
/**
* Imports a list of items from a `.txt` or `.csv` file. The maximum file size is 9 million bytes.
* Import list items from a TXT or CSV file. The maximum file size is 9 million bytes.
You can import items to a new or existing list.
@ -127,6 +159,9 @@ You can import items to a new or existing list.
.set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
.query(props.query);
},
/**
* Update specific fields of an existing list using the list ID.
*/
patchList(props: PatchListProps, kibanaSpace: string = 'default') {
return supertest
.patch(routeWithNamespace('/api/lists', kibanaSpace))
@ -135,6 +170,9 @@ You can import items to a new or existing list.
.set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
.send(props.body as object);
},
/**
* Update specific fields of an existing list item using the list item ID.
*/
patchListItem(props: PatchListItemProps, kibanaSpace: string = 'default') {
return supertest
.patch(routeWithNamespace('/api/lists/items', kibanaSpace))
@ -143,6 +181,9 @@ You can import items to a new or existing list.
.set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
.send(props.body as object);
},
/**
* Get the details of a list using the list ID.
*/
readList(props: ReadListProps, kibanaSpace: string = 'default') {
return supertest
.get(routeWithNamespace('/api/lists', kibanaSpace))
@ -151,6 +192,9 @@ You can import items to a new or existing list.
.set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
.query(props.query);
},
/**
* Verify that `.lists` and `.items` data streams exist.
*/
readListIndex(kibanaSpace: string = 'default') {
return supertest
.get(routeWithNamespace('/api/lists/index', kibanaSpace))
@ -158,6 +202,9 @@ You can import items to a new or existing list.
.set(ELASTIC_HTTP_VERSION_HEADER, '2023-10-31')
.set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana');
},
/**
* Get the details of a list item.
*/
readListItem(props: ReadListItemProps, kibanaSpace: string = 'default') {
return supertest
.get(routeWithNamespace('/api/lists/items', kibanaSpace))
@ -173,6 +220,12 @@ You can import items to a new or existing list.
.set(ELASTIC_HTTP_VERSION_HEADER, '2023-10-31')
.set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana');
},
/**
* Update a list using the list ID. The original list is replaced, and all unspecified fields are deleted.
> info
> You cannot modify the `id` value.
*/
updateList(props: UpdateListProps, kibanaSpace: string = 'default') {
return supertest
.put(routeWithNamespace('/api/lists', kibanaSpace))
@ -181,6 +234,12 @@ You can import items to a new or existing list.
.set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
.send(props.body as object);
},
/**
* Update a list item using the list item ID. The original list item is replaced, and all unspecified fields are deleted.
> info
> You cannot modify the `id` value.
*/
updateListItem(props: UpdateListItemProps, kibanaSpace: string = 'default') {
return supertest
.put(routeWithNamespace('/api/lists/items', kibanaSpace))