Add automation for first two CAT APIs #8930

Naarcha-AWS · 2024-12-11T16:27:38Z

Adds automation for first two CAT APIs

Checklist

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license and subject to the Developers Certificate of Origin.
For more information on following Developer Certificate of Origin and signing off your commits, please check here.

Signed-off-by: Archer <[email protected]>

github-actions · 2024-12-11T16:27:51Z

Thank you for submitting your PR. The PR states are In progress (or Draft) -> Tech review -> Doc review -> Editorial review -> Merged.

Before you submit your PR for doc review, make sure the content is technically accurate. If you need help finding a tech reviewer, tag a maintainer.

When you're ready for doc review, tag the assignee of this PR. The doc reviewer may push edits to the PR directly or leave comments and editorial suggestions for you to address (let us know in a comment if you have a preference). The doc reviewer will arrange for an editorial review.

kolchfa-aws

Some suggestions to clarify the descriptions. Please include default values where appropriate. Thanks.

kolchfa-aws · 2024-12-11T17:42:32Z

_api-reference/cat/cat-aliases.md

+api: cat.aliases
+component: paths_and_http_methods
+-->
+## Paths and HTTP methods


Suggested change

## Paths and HTTP methods

## Path and HTTP methods

Do we want Paths when there many and Path when there's one?
Or do want a universal one? If it's universal then Paths and HTTP methods makes more sense.

I prefer Paths and HTTP methods. If we need to change to the singular (which in this case we don't, since multiple path types exist), we can exclude the header and modify it in the options.

@nhtruong: @kolchfa-aws and I discussed it. Path would be more accurate than Paths since each x-operation-id usually encompasses one path in the API. We'll use omit_header if the writer chooses to include multiple paths on a single page.

Thanks. Multiple paths on a single page would still be documented as different APIs and thus be in different sections.

Please use Path and HTTP methods per the API Style Guide.

Let's use "Endpoints" because "API operation" is not specific enough.

My primary concern here is consistency. If we want to use "Endpoints", that's fine, but let's reflect that in the template as well as in the relevant docs. Thanks.

I'll change the template and the wording in a separate PR.

The PR is up #8959

kolchfa-aws · 2024-12-11T17:45:47Z

_api-reference/cat/cat-aliases.md

 Parameter | Type | Description
 :--- | :--- | :---
-local | Boolean | Whether to return information from the local node only instead of from the cluster manager node. Default is `false`.
-expand_wildcards | Enum | Expands wildcard expressions to concrete indexes. Combine multiple values with commas. Supported values are `all`, `open`, `closed`, `hidden`, and `none`. Default is `open`.
+`expand_wildcards` | String / String / String / String / List | Whether to expand wildcard expression to concrete indexes that are open, closed or both.


Why are there 4 instances of String in the type? Also, as a rule, we don't want slashes to signify "or". I would suggest "String or list". Also, the old description had supported values, which is helpful, and specified that the list should be comma-separated. The new description has less information.

@nhtruong: IS there something in the spec that would cause this?

That's coming form the spec. I'll update the code to handle this edge case.

Sounds good. Let me know once that update is through and I'll update this PR with the updated descriptions.

kolchfa-aws · 2024-12-11T17:48:39Z

_api-reference/cat/cat-allocation.md

-bytes | Byte size | Specify the units for byte size. For example, `7kb` or `6gb`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
-local | Boolean | Whether to return information from the local node only instead of from the cluster manager node. Default is `false`.
-cluster_manager_timeout | Time | The amount of time to wait for a connection to the cluster manager node. Default is 30 seconds.
+`bytes` | String | The unit used to display byte values.


Suggested change

`bytes` | String | The unit used to display byte values.

`bytes` | String | The units used to display byte values.

kolchfa-aws · 2024-12-11T17:48:57Z

_api-reference/cat/cat-allocation.md

-local | Boolean | Whether to return information from the local node only instead of from the cluster manager node. Default is `false`.
-cluster_manager_timeout | Time | The amount of time to wait for a connection to the cluster manager node. Default is 30 seconds.
+`bytes` | String | The unit used to display byte values.
+`cluster_manager_timeout` | String | Operation timeout for connection to cluster-manager node.


Suggested change

`cluster_manager_timeout` | String | Operation timeout for connection to cluster-manager node.

`cluster_manager_timeout` | String | A timeout for connection to the cluster manager node.

kolchfa-aws · 2024-12-11T17:49:21Z

_api-reference/cat/cat-allocation.md

-cluster_manager_timeout | Time | The amount of time to wait for a connection to the cluster manager node. Default is 30 seconds.
+`bytes` | String | The unit used to display byte values.
+`cluster_manager_timeout` | String | Operation timeout for connection to cluster-manager node.
+`format` | String | A short version of the Accept header (for example, `json`, `yaml`).


Suggested change

`format` | String | A short version of the Accept header (for example, `json`, `yaml`).

`format` | String | A short version of the HTTP accept header (for example, `json` or `yaml`).

kolchfa-aws · 2024-12-11T17:51:25Z

_api-reference/cat/cat-allocation.md

+`format` | String | A short version of the Accept header (for example, `json`, `yaml`).
+`h` | List | Comma-separated list of column names to display.
+`help` | Boolean | Return help information.
+`local` | Boolean | Return local information, do not retrieve the state from cluster-manager node.


Suggested change

`local` | Boolean | Return local information, do not retrieve the state from cluster-manager node.

`local` | Boolean | If `true`, specifies to retrieve information only from the local node. If `false`, specifies to retrieve local information from the cluster manager node.

kolchfa-aws · 2024-12-11T17:51:50Z

_api-reference/cat/cat-allocation.md

+`h` | List | Comma-separated list of column names to display.
+`help` | Boolean | Return help information.
+`local` | Boolean | Return local information, do not retrieve the state from cluster-manager node.
+`s` | List | Comma-separated list of column names or column aliases to sort by.


Suggested change

`s` | List | Comma-separated list of column names or column aliases to sort by.

`s` | List | A comma-separated list of column names or column aliases to sort the response.

kolchfa-aws · 2024-12-11T17:52:10Z

_api-reference/cat/cat-allocation.md

+`help` | Boolean | Return help information.
+`local` | Boolean | Return local information, do not retrieve the state from cluster-manager node.
+`s` | List | Comma-separated list of column names or column aliases to sort by.
+`v` | Boolean | Verbose mode. Display column headers.


Suggested change

`v` | Boolean | Verbose mode. Display column headers.

`v` | Boolean | Whether to display column headers.

kolchfa-aws · 2024-12-11T17:52:51Z

_api-reference/cat/cat-allocation.md

+api: cat.allocation
+component: query_parameters
+-->
+## Query parameters
 Parameter | Type | Description
 :--- | :--- | :---


We also need to specify defaults for the query parameters that have them (e.g., local).

kolchfa-aws · 2024-12-11T17:53:17Z

_api-reference/cat/cat-cluster_manager.md

+api: cat.cluster_manager
+component: query_parameters
+-->
+## Query parameters


Same comments as above.

Signed-off-by: Naarcha-AWS <[email protected]>

Signed-off-by: Archer <[email protected]>

_api-reference/cat/cat-allocation.md

Co-authored-by: kolchfa-aws <[email protected]> Signed-off-by: Naarcha-AWS <[email protected]>

* Add automation for first three CAT APIs Signed-off-by: Archer <[email protected]> * Add pointers for Aliases and Allocation. Remove for cluster_manager. Signed-off-by: Archer <[email protected]> * Add updated specs Signed-off-by: Archer <[email protected]> * Update _api-reference/cat/cat-allocation.md Co-authored-by: kolchfa-aws <[email protected]> Signed-off-by: Naarcha-AWS <[email protected]> --------- Signed-off-by: Archer <[email protected]> Signed-off-by: Naarcha-AWS <[email protected]> Co-authored-by: kolchfa-aws <[email protected]> (cherry picked from commit 1006421) Signed-off-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Add automation for first three CAT APIs

ac3055f

Signed-off-by: Archer <[email protected]>

Naarcha-AWS requested review from kolchfa-aws, AMoo-Miki, natebower, dlvenable and epugh as code owners December 11, 2024 16:27

Naarcha-AWS self-assigned this Dec 11, 2024

Naarcha-AWS added backport 2.18 PR: Backport label for 2.18 4 - Doc review PR: Doc review in progress labels Dec 11, 2024

kolchfa-aws reviewed Dec 11, 2024

View reviewed changes

kolchfa-aws mentioned this pull request Dec 11, 2024

Update Cat API query descriptions. opensearch-project/opensearch-api-specification#726

Merged

Naarcha-AWS and others added 4 commits December 19, 2024 12:32

Merge branch 'main' into api-reference-cat

c29685d

Signed-off-by: Naarcha-AWS <[email protected]>

Add pointers for Aliases and Allocation. Remove for cluster_manager.

be747a7

Signed-off-by: Archer <[email protected]>

Merge branch 'main' into api-reference-cat

a7205d1

Add updated specs

d33d12a

Signed-off-by: Archer <[email protected]>

Naarcha-AWS changed the title ~~Add automation for first three CAT APIs~~ Add automation for first two CAT APIs Dec 19, 2024

kolchfa-aws approved these changes Dec 19, 2024

View reviewed changes

_api-reference/cat/cat-allocation.md Outdated Show resolved Hide resolved

Update _api-reference/cat/cat-allocation.md

29f17f3

Co-authored-by: kolchfa-aws <[email protected]> Signed-off-by: Naarcha-AWS <[email protected]>

Naarcha-AWS merged commit 1006421 into main Dec 19, 2024
6 checks passed

opensearch-trigger-bot bot mentioned this pull request Dec 19, 2024

[Backport 2.18] Add automation for first two CAT APIs #8976

Merged

github-actions bot pushed a commit that referenced this pull request Dec 19, 2024

Add automation for first two CAT APIs (#8930) (#8976)

dd44ecb

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add automation for first two CAT APIs #8930

Add automation for first two CAT APIs #8930

Naarcha-AWS commented Dec 11, 2024 •

edited

Loading

github-actions bot commented Dec 11, 2024

kolchfa-aws left a comment

kolchfa-aws Dec 11, 2024

nhtruong Dec 12, 2024

Naarcha-AWS Dec 12, 2024

Naarcha-AWS Dec 12, 2024

kolchfa-aws Dec 12, 2024

natebower Dec 16, 2024

kolchfa-aws Dec 16, 2024

natebower Dec 16, 2024

kolchfa-aws Dec 16, 2024

kolchfa-aws Dec 16, 2024

kolchfa-aws Dec 11, 2024

Naarcha-AWS Dec 11, 2024

nhtruong Dec 12, 2024

Naarcha-AWS Dec 12, 2024

kolchfa-aws Dec 11, 2024

kolchfa-aws Dec 11, 2024

kolchfa-aws Dec 11, 2024

kolchfa-aws Dec 11, 2024

kolchfa-aws Dec 11, 2024

kolchfa-aws Dec 11, 2024

kolchfa-aws Dec 11, 2024

kolchfa-aws Dec 11, 2024

	`bytes` \| String \| The unit used to display byte values.
	`bytes` \| String \| The units used to display byte values.

	`cluster_manager_timeout` \| String \| Operation timeout for connection to cluster-manager node.
	`cluster_manager_timeout` \| String \| A timeout for connection to the cluster manager node.

	`format` \| String \| A short version of the Accept header (for example, `json`, `yaml`).
	`format` \| String \| A short version of the HTTP accept header (for example, `json` or `yaml`).

	`local` \| Boolean \| Return local information, do not retrieve the state from cluster-manager node.
	`local` \| Boolean \| If `true`, specifies to retrieve information only from the local node. If `false`, specifies to retrieve local information from the cluster manager node.

	`s` \| List \| Comma-separated list of column names or column aliases to sort by.
	`s` \| List \| A comma-separated list of column names or column aliases to sort the response.

	`v` \| Boolean \| Verbose mode. Display column headers.
	`v` \| Boolean \| Whether to display column headers.

Add automation for first two CAT APIs #8930

Add automation for first two CAT APIs #8930

Conversation

Naarcha-AWS commented Dec 11, 2024 • edited Loading

Checklist

github-actions bot commented Dec 11, 2024

kolchfa-aws left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Naarcha-AWS commented Dec 11, 2024 •

edited

Loading